@pithy-sh/support 0.5.1 → 0.6.0

package/src/semantic/messageIndex.ts

@@ -0,0 +1,74 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type FeatureIdentity, featureVectorizeIndexName } from "@pithy-sh/core/src/naming/feature";
+import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+import type { VectorIndexConfig } from "@pithy-sh/vector/src/config/config";
+import type { VectorIndexShape } from "@pithy-sh/vector/src/provision/provisionVector";
+import { type SupportSearchConfig, supportSemantic } from "../config/config";
+
+/**
+ * The semantic message index — what it is called, what shape it has, and what text goes into it.
+ *
+ * **Support owns it, through `@pithy-sh/vector`'s public modules, and the adopter composes no `vector()`.** The
+ * index is declared here as a {@link VectorIndexConfig}, the same value `vector()` builds from an adopter's
+ * `indexes` block, so `embedForIndex`, `queryVectors` and the reprocess orchestration take it unchanged and pin
+ * the model on writes and queries alike.
+ *
+ * **Vectors carry ids and nothing else.** A vector's id is the message's id, and no subject, body or address
+ * reaches Vectorize metadata: the text stays in D1 under the privacy markers its schema carries. A match is
+ * resolved back to its thread in D1, which is also where every filter applies.
+ */
+
+/** The index's name in `pithy vector reprocess --index`, and the `<thing>` its Cloudflare name ends with. */
+export const SUPPORT_MESSAGES_INDEX = "support-messages";
+
+/** The Vectorize binding the index arrives on, in the app Worker and the classification worker alike. */
+export const SUPPORT_VECTORIZE_BINDING = "SUPPORT_VECTORIZE";
+
+/** The Workers AI binding a query and an inbound message are embedded on. */
+export const SUPPORT_AI_BINDING = "AI";
+
+/**
+ * How much of a message is embedded. A support message states its point early, and the rest is usually a
+ * quoted thread and a signature — text that would pull every vector toward the same neighborhood.
+ */
+export const MAX_EMBED_CHARS = 4000;
+
+/** The index this search config asks for, or `undefined` when `search.semantic` is off. */
+export function supportMessageIndex(search: SupportSearchConfig): VectorIndexConfig | undefined {
+  const semantic = supportSemantic(search);
+  if (!semantic) return undefined;
+  return {
+    model: semantic.model,
+    dimensions: semantic.dimensions,
+    // Text embeddings, compared by angle. Fixed at creation.
+    metric: "cosine",
+    binding: SUPPORT_VECTORIZE_BINDING,
+  };
+}
+
+/**
+ * The shape `pithy support provision` creates the index with — `vector`'s own provisioning shape, so a support
+ * index and a `vector()` index are created, and refused on a mismatch, by the same rule. `undefined` when off.
+ */
+export function supportMessageIndexShape(search: SupportSearchConfig): VectorIndexShape | undefined {
+  const index = supportMessageIndex(search);
+  return index ? { dimensions: index.dimensions, metric: index.metric } : undefined;
+}
+
+/**
+ * The index's Cloudflare name — `<project>-<env>-support-messages`, or a feature's own.
+ *
+ * Through the naming facade, which refuses a Vectorize name over 64 bytes rather than truncating it: a shortened
+ * name is a different, empty index.
+ */
+export function supportMessageIndexName(project: string, env: string, feature?: FeatureIdentity): string {
+  if (feature) return featureVectorizeIndexName(feature, SUPPORT_MESSAGES_INDEX);
+  return resourceNames(project).env(env).vectorizeIndex(SUPPORT_MESSAGES_INDEX);
+}
+
+/** The text one message is embedded as: its subject, then its body, bounded. */
+export function embeddingText(subject: string, body: string): string {
+  return `${subject}\n\n${body}`.slice(0, MAX_EMBED_CHARS);
+}

package/src/semantic/query.ts

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { chunkByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+import type { VectorIndexConfig } from "@pithy-sh/vector/src/config/config";
+import { embedForIndex, type VectorAi } from "@pithy-sh/vector/src/embed/embed";
+import { queryVectors, type VectorStore } from "@pithy-sh/vector/src/index/index";
+import { SUPPORT_MESSAGES_TABLE, type SupportDatabase } from "../data/tables";
+import type { MessageHit } from "../store/search";
+
+/**
+ * The semantic half of a search: embed the query with the index's pinned model, ask Vectorize for the nearest
+ * message ids, and resolve each to its thread in D1.
+ *
+ * **Ids without payload, so the ceiling is 100.** Vectorize allows 100 matches when it returns neither values
+ * nor metadata, and the vectors carry no metadata worth returning anyway. A thread is then scored by its best
+ * message, so a hundred messages roll up to the threads a page of results needs.
+ *
+ * A match whose message is gone — purged, say, before its vector was — resolves to nothing and is dropped.
+ */
+
+/**
+ * How many message ids the semantic side asks for: Vectorize's ceiling for a payload-free query. Stated here
+ * rather than imported, so support reaches only `vector`'s embed, index, provisioning and reprocess modules;
+ * `vectorImports.test.ts` holds it to `vector`'s own constant.
+ */
+export const SEMANTIC_TOP_K = 100;
+
+/** What a semantic query needs. */
+export interface SemanticQueryDeps {
+  /** The support tables, where each match is resolved to its thread. */
+  db: SupportDatabase;
+  /** The Workers AI binding. */
+  ai: VectorAi;
+  /** The message index's Vectorize binding. */
+  store: VectorStore;
+  /** The index's config. */
+  index: VectorIndexConfig;
+}
+
+/** The messages nearest in meaning to `term`, best first, each with its raw similarity. */
+export async function semanticHits(deps: SemanticQueryDeps, term: string): Promise<MessageHit[]> {
+  const [vector] = await embedForIndex(deps.ai, deps.index, [term]);
+  const result = await queryVectors(deps.store, deps.index, vector as number[], { topK: SEMANTIC_TOP_K });
+  if (result.matches.length === 0) return [];
+
+  const threadOf = new Map<string, string>();
+  for (const group of chunkByBoundParameters(
+    result.matches.map((match) => match.id),
+    0,
+  )) {
+    const rows = await deps.db
+      .selectFrom(SUPPORT_MESSAGES_TABLE)
+      .select(["id", "threadId"])
+      .where("id", "in", group)
+      .execute();
+    for (const row of rows) threadOf.set(row.id, row.threadId);
+  }
+
+  const hits: MessageHit[] = [];
+  for (const match of result.matches) {
+    const threadId = threadOf.get(match.id);
+    if (threadId !== undefined) hits.push({ messageId: match.id, threadId, score: match.score });
+  }
+  return hits;
+}

package/src/staff/staff.ts

@@ -0,0 +1,128 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ActingOrganization } from "@pithy-sh/core/src/access/acting";
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { SupportStaffConfig } from "../config/config";
+
+/**
+ * **Who of the app's own signed-in users works the inbox** (#816) — `support({ staff })`.
+ *
+ * Asked of core's acting-organization seam, which `@pithy-sh/organization` fills from a membership row
+ * read on this request; never imported, so without organization nobody is staff and every staff route
+ * refuses. The catalog is read by shape at compose, the way `artifacts` reads it, so support depends on
+ * no tenancy package.
+ */
+
+/** The catalog support reads off a composed organization capability. Everything else about it is ignored. */
+interface StaffCatalog {
+  readonly powers: readonly string[];
+  readonly roles: readonly string[];
+  readonly assignableRoles: readonly string[];
+  roleAllows(role: string, power: string): boolean;
+}
+
+/** A composed capability's role catalog, read by shape, or undefined when it carries none. */
+function catalogOf(capability: Capability): StaffCatalog | undefined {
+  const catalog = (capability as { organizationRoles?: Partial<StaffCatalog> }).organizationRoles;
+  if (
+    !catalog ||
+    !Array.isArray(catalog.powers) ||
+    !Array.isArray(catalog.roles) ||
+    !Array.isArray(catalog.assignableRoles) ||
+    typeof catalog.roleAllows !== "function"
+  ) {
+    return undefined;
+  }
+  return catalog as StaffCatalog;
+}
+
+/**
+ * The role a composed ownership transfer confers, read by shape, or undefined where there is no transfer.
+ *
+ * Unassignable, always — organization refuses a transfer onto an assignable role — and still self-served:
+ * anybody may found an organization, every new organization starts with no holder, and with no holder an
+ * administrator may nominate themselves and accept. So an unassignable role is out of an organization's
+ * own reach only when it is not this one.
+ */
+function ownershipRoleOf(capability: Capability): string | undefined {
+  const confers = (capability as { organizationOwnership?: { confers?: unknown } }).organizationOwnership?.confers;
+  return typeof confers === "string" ? confers : undefined;
+}
+
+/** Refuse a staff composition at boot, naming what is wrong and what to change. */
+function refuse(message: string, action: string, detail: string): never {
+  throw new InternalError({ message, action, detail });
+}
+
+/**
+ * Refuse, at compose, a staff block no request could be served by safely.
+ *
+ * Four refusals. **No organization**: a power is held in an organization, so with none composed nobody
+ * could ever be staff and the block is a mistake rather than a policy. **A power the catalog does not
+ * declare, or no role holds**: the same, by a typo. **A power on an assignable role**: a role is the
+ * catalog's and not one organization's, and an organization's own administrator may give any assignable
+ * role to their own members — so the power would make every customer's administrator able to read every
+ * other customer's support mail. **A power on the role ownership transfer confers**: unassignable, and
+ * still one any signed-in user can take — found an organization, nominate yourself, accept — so it opens
+ * the same inbox to the same people. On any other unassignable role it is conferred through the control
+ * plane alone, by an operator.
+ */
+export function assertStaffComposition(
+  staff: SupportStaffConfig | undefined,
+  capabilities: readonly Capability[],
+): void {
+  if (!staff) return;
+  const tenancy = capabilities.find((candidate) => candidate.name === "organization");
+  const catalog = tenancy ? catalogOf(tenancy) : undefined;
+  if (!catalog) {
+    refuse(
+      "support() names staff powers, and organization is not composed.",
+      "Compose organization() with a role catalog that declares them, or remove `staff` from support().",
+      "a staff power is held in an organization; with none composed nobody could ever hold one",
+    );
+  }
+  const ownership = tenancy ? ownershipRoleOf(tenancy) : undefined;
+  for (const power of [staff.readPower, staff.assignPower]) {
+    if (!catalog.powers.includes(power)) {
+      refuse(
+        `support() names staff power \`${power}\`, which your role catalog does not declare.`,
+        "Declare it in defineRoles({ powers }) and give it to an unassignable role your staff hold, other than the one ownership transfer confers.",
+        `declared powers: ${catalog.powers.join(", ")}`,
+      );
+    }
+    const holders = catalog.roles.filter((role) => catalog.roleAllows(role, power));
+    if (holders.length === 0) {
+      refuse(
+        `No role in your catalog holds support's staff power \`${power}\`.`,
+        "Give it to an unassignable role your staff hold, other than the one ownership transfer confers.",
+        `power ${power} is declared and held by no role`,
+      );
+    }
+    const handable = holders.filter((role) => catalog.assignableRoles.includes(role));
+    if (handable.length > 0) {
+      refuse(
+        `Support's staff power \`${power}\` is on a role an organization may hand out: ${handable.join(", ")}.`,
+        "Move it to a role listed in defineRoles({ unassignable }) that ownership transfer does not confer, so only an operator can confer it.",
+        `an organization administrator may assign ${handable.join(", ")} to their own members, which would open every customer's support mail to them`,
+      );
+    }
+    if (ownership !== undefined && holders.includes(ownership)) {
+      refuse(
+        `Support's staff power \`${power}\` is on \`${ownership}\`, the role ownership transfer confers, which an organization's founder may take alone.`,
+        "Move it to a role listed in defineRoles({ unassignable }) that ownership transfer does not confer, so only an operator can confer it.",
+        `anybody may found an organization and nominate themselves as its ${ownership}, which would open every customer's support mail to them`,
+      );
+    }
+  }
+}
+
+/** Whether the organization this request acts for gives the caller one of support's staff powers. */
+export function staffMay(
+  acting: ActingOrganization | null,
+  staff: SupportStaffConfig | undefined,
+  power: keyof SupportStaffConfig,
+): boolean {
+  return acting !== null && staff !== undefined && acting.roleAllows(staff[power]);
+}

package/src/store/assignment.ts

@@ -0,0 +1,179 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database, D1PreparedStatement } from "@cloudflare/workers-types";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { type CompiledQuery, type SqlBool, sql } from "kysely";
+import { SupportAssignment, type SupportAssignmentActorType } from "../data/assignment";
+import {
+  SUPPORT_ASSIGNMENTS_TABLE,
+  SUPPORT_THREADS_TABLE,
+  type SupportDatabase,
+  supportDatabase,
+} from "../data/tables";
+import { SupportThread } from "../data/thread";
+import { SupportNotFoundError } from "../error/errors";
+
+/**
+ * Who has a thread (#816).
+ *
+ * **One fact, not a state machine.** A thread has an assignee or it has none, and any change moves it
+ * straight to the next one. Every real change appends a row to `pithy_support_assignments`; a change that
+ * changes nothing — the current assignee again, or unassigning a thread nobody has — writes nothing at
+ * all, which is what lets a caller emit its audit event only when something happened.
+ *
+ * **Compare-and-set, not last-write-wins on a read.** The previous assignee is part of what the history and
+ * the audit event record, so the write is conditioned on the assignee this call read. Two handovers racing
+ * from one state cannot both claim to have replaced the same person: the loser re-reads and replaces
+ * whoever won, and the chain of `previousRef` stays unbroken.
+ *
+ * **The change and its history row land together or not at all.** The conditional update and the history
+ * insert go to D1 as one batch, which D1 runs as one transaction, and the insert is guarded on the update
+ * having changed a row. A history row that cannot be written rolls the assignee back with it, so a retry
+ * sees the old assignee, makes the change again, and records it — rather than finding the change already
+ * made, taking the no-op branch, and leaving that handover out of the history and the audit trail for good.
+ */
+
+/** Somebody a thread may be assigned to: an opaque reference and how to show it. */
+export interface Assignee {
+  /** Opaque — a dashboard member, a user of the app, an agent. Support never interprets it. */
+  ref: string;
+  /** Display text, as the assigner named them. */
+  name: string;
+}
+
+/** What {@link assignThread} takes. */
+export interface AssignThreadOptions {
+  /** The thread. */
+  threadId: string;
+  /** Who should have it, or null for nobody. */
+  assignee: Assignee | null;
+  /** How the assigner was verified. */
+  actorType: SupportAssignmentActorType;
+  /** The control-plane subject, or the signed-in user's id. */
+  assignedBy: string;
+  /** Why, when the assigner said. */
+  note?: string;
+  /** Generate a history row id. */
+  newId: () => string;
+  /** Now. */
+  now: Date;
+}
+
+/** What {@link assignThread} did. */
+export interface AssignThreadResult {
+  /** The thread as it now stands. */
+  thread: SupportThread;
+  /** Whether anything changed. False for the current assignee again, or for unassigning nobody. */
+  changed: boolean;
+  /** Who had it before this call, or null when nobody did. */
+  previous: Assignee | null;
+}
+
+/** How many times a write lost to a concurrent one is retried before the request gives up. */
+const MAX_ATTEMPTS = 5;
+
+/** The assignee a thread row names, or null. */
+function assigneeOf(thread: SupportThread): Assignee | null {
+  return thread.assigneeRef ? { ref: thread.assigneeRef, name: thread.assigneeName ?? thread.assigneeRef } : null;
+}
+
+/** A compiled Kysely query as a D1 statement, for a batch. */
+function prepared(d1: D1Database, compiled: CompiledQuery): D1PreparedStatement {
+  return d1.prepare(compiled.sql).bind(...(compiled.parameters as unknown[]));
+}
+
+/**
+ * Insert a history row only when the statement before it changed a row — `changes()` answers for the
+ * statement just before it in the batch — so a compare-and-set that matched nothing writes no history.
+ */
+function guardedHistory(db: SupportDatabase, row: Record<string, unknown>): CompiledQuery {
+  const columns = Object.keys(row);
+  return (
+    db
+      .insertInto(SUPPORT_ASSIGNMENTS_TABLE)
+      // biome-ignore lint/suspicious/noExplicitAny: the encoded row's own keys, which are the table's columns.
+      .columns(columns as any)
+      .expression(
+        db.selectNoFrom(columns.map((column) => sql.val(row[column]).as(column))).where(sql<SqlBool>`changes() > 0`),
+      )
+      .compile()
+  );
+}
+
+/** Assign a thread, or unassign it. Throws `support/not_found` when it does not exist. */
+export async function assignThread(d1: D1Database, options: AssignThreadOptions): Promise<AssignThreadResult> {
+  const db = supportDatabase(d1);
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const row = await db
+      .selectFrom(SUPPORT_THREADS_TABLE)
+      .selectAll()
+      .where("id", "=", options.threadId)
+      .executeTakeFirst();
+    if (!row) throw new SupportNotFoundError({ detail: `no support thread ${options.threadId}` });
+    const current = SupportThread.parse(row);
+    const previous = assigneeOf(current);
+
+    // The same ref is the same person, whatever name it arrives under: a no-op, so nothing is written,
+    // nothing is recorded, and the caller emits nothing.
+    if ((previous?.ref ?? null) === (options.assignee?.ref ?? null)) {
+      return { thread: current, changed: false, previous };
+    }
+
+    const now = options.now.getTime();
+    const next = {
+      assigneeRef: options.assignee?.ref ?? null,
+      assigneeName: options.assignee?.name ?? null,
+      assignedAt: options.assignee ? now : null,
+      assignedBy: options.assignee ? options.assignedBy : null,
+      updatedAt: now,
+    };
+    const update = db
+      .updateTable(SUPPORT_THREADS_TABLE)
+      .set(next)
+      .where("id", "=", options.threadId)
+      // `is`, so a null previous assignee compares as SQLite's null-safe equality rather than never matching.
+      .where("assigneeRef", "is", previous?.ref ?? null)
+      .compile();
+    const history = guardedHistory(
+      db,
+      SupportAssignment.encode({
+        id: options.newId(),
+        threadId: options.threadId,
+        assigneeRef: options.assignee?.ref ?? null,
+        assigneeName: options.assignee?.name ?? null,
+        previousRef: previous?.ref ?? null,
+        previousName: previous?.name ?? null,
+        actorType: options.actorType,
+        assignedBy: options.assignedBy,
+        note: options.note ?? null,
+        createdAt: options.now,
+      }) as Record<string, unknown>,
+    );
+    const [updated] = await d1.batch([prepared(d1, update), prepared(d1, history)]);
+    if ((updated?.meta.changes ?? 0) === 0) continue;
+
+    return {
+      thread: SupportThread.parse({ ...row, ...next }),
+      changed: true,
+      previous,
+    };
+  }
+  throw new InternalError({
+    message: "That conversation is being reassigned by somebody else. Try again.",
+    detail: `assignment of thread ${options.threadId} lost ${MAX_ATTEMPTS} races in a row`,
+  });
+}
+
+/** A thread's assignee history, oldest first. */
+export async function listAssignments(db: SupportDatabase, threadId: string): Promise<SupportAssignment[]> {
+  const rows = await db
+    .selectFrom(SUPPORT_ASSIGNMENTS_TABLE)
+    .selectAll()
+    .where("threadId", "=", threadId)
+    .orderBy("createdAt", "asc")
+    // Insertion order breaks a tie within one millisecond, so the chain reads in the order it was written.
+    .orderBy(sql`rowid`, "asc")
+    .execute();
+  return rows.map((row) => SupportAssignment.parse(row));
+}