@pithy-sh/support 0.5.1 → 0.6.0

package/dist/semantic/messageIndex.js

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { supportSemantic } from "../config/config.js";
+import { featureVectorizeIndexName } from "@pithy-sh/core/src/naming/feature";
+import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+//#region src/semantic/messageIndex.ts
+/**
+* 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. */
+const SUPPORT_MESSAGES_INDEX = "support-messages";
+/** The Vectorize binding the index arrives on, in the app Worker and the classification worker alike. */
+const SUPPORT_VECTORIZE_BINDING = "SUPPORT_VECTORIZE";
+/** The Workers AI binding a query and an inbound message are embedded on. */
+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.
+*/
+const MAX_EMBED_CHARS = 4e3;
+/** The index this search config asks for, or `undefined` when `search.semantic` is off. */
+function supportMessageIndex(search) {
+	const semantic = supportSemantic(search);
+	if (!semantic) return void 0;
+	return {
+		model: semantic.model,
+		dimensions: semantic.dimensions,
+		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.
+*/
+function supportMessageIndexShape(search) {
+	const index = supportMessageIndex(search);
+	return index ? {
+		dimensions: index.dimensions,
+		metric: index.metric
+	} : void 0;
+}
+/**
+* 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.
+*/
+function supportMessageIndexName(project, env, feature) {
+	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. */
+function embeddingText(subject, body) {
+	return `${subject}\n\n${body}`.slice(0, MAX_EMBED_CHARS);
+}
+//#endregion
+export { MAX_EMBED_CHARS, SUPPORT_AI_BINDING, SUPPORT_MESSAGES_INDEX, SUPPORT_VECTORIZE_BINDING, embeddingText, supportMessageIndex, supportMessageIndexName, supportMessageIndexShape };

package/dist/semantic/query.d.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { VectorIndexConfig } from "@pithy-sh/vector/src/config/config";
+import { type VectorAi } from "@pithy-sh/vector/src/embed/embed";
+import { type VectorStore } from "@pithy-sh/vector/src/index/index";
+import { 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 declare 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 declare function semanticHits(deps: SemanticQueryDeps, term: string): Promise<MessageHit[]>;
+//# sourceMappingURL=query.d.ts.map

package/dist/semantic/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/semantic/query.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAChF,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAClF,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,mCAAmC;AACnC,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,EAAE,EAAE,eAAe,CAAC;IACpB,8BAA8B;IAC9B,EAAE,EAAE,QAAQ,CAAC;IACb,6CAA6C;IAC7C,KAAK,EAAE,WAAW,CAAC;IACnB,0BAA0B;IAC1B,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAED,2FAA2F;AAC3F,wBAAsB,YAAY,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAwB/F"}

package/dist/semantic/query.js

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SUPPORT_MESSAGES_TABLE } from "../data/tables.js";
+import { chunkByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+import { embedForIndex } from "@pithy-sh/vector/src/embed/embed";
+import { queryVectors } from "@pithy-sh/vector/src/index/index";
+//#region src/semantic/query.ts
+/**
+* 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.
+*/
+const SEMANTIC_TOP_K = 100;
+/** The messages nearest in meaning to `term`, best first, each with its raw similarity. */
+async function semanticHits(deps, term) {
+	const [vector] = await embedForIndex(deps.ai, deps.index, [term]);
+	const result = await queryVectors(deps.store, deps.index, vector, { topK: 100 });
+	if (result.matches.length === 0) return [];
+	const threadOf = /* @__PURE__ */ new Map();
+	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 = [];
+	for (const match of result.matches) {
+		const threadId = threadOf.get(match.id);
+		if (threadId !== void 0) hits.push({
+			messageId: match.id,
+			threadId,
+			score: match.score
+		});
+	}
+	return hits;
+}
+//#endregion
+export { SEMANTIC_TOP_K, semanticHits };

package/dist/staff/staff.d.ts

@@ -0,0 +1,22 @@
+// 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 type { SupportStaffConfig } from "../config/config";
+/**
+ * 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 declare function assertStaffComposition(staff: SupportStaffConfig | undefined, capabilities: readonly Capability[]): void;
+/** Whether the organization this request acts for gives the caller one of support's staff powers. */
+export declare function staffMay(acting: ActingOrganization | null, staff: SupportStaffConfig | undefined, power: keyof SupportStaffConfig): boolean;
+//# sourceMappingURL=staff.d.ts.map

package/dist/staff/staff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staff.d.ts","sourceRoot":"","sources":["../../src/staff/staff.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAoD3D;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,GAAG,SAAS,EACrC,YAAY,EAAE,SAAS,UAAU,EAAE,GAClC,IAAI,CA4CN;AAED,qGAAqG;AACrG,wBAAgB,QAAQ,CACtB,MAAM,EAAE,kBAAkB,GAAG,IAAI,EACjC,KAAK,EAAE,kBAAkB,GAAG,SAAS,EACrC,KAAK,EAAE,MAAM,kBAAkB,GAC9B,OAAO,CAET"}

package/dist/staff/staff.js

@@ -0,0 +1,64 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/staff/staff.ts
+/** A composed capability's role catalog, read by shape, or undefined when it carries none. */
+function catalogOf(capability) {
+	const catalog = capability.organizationRoles;
+	if (!catalog || !Array.isArray(catalog.powers) || !Array.isArray(catalog.roles) || !Array.isArray(catalog.assignableRoles) || typeof catalog.roleAllows !== "function") return;
+	return catalog;
+}
+/**
+* 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) {
+	const confers = capability.organizationOwnership?.confers;
+	return typeof confers === "string" ? confers : void 0;
+}
+/** Refuse a staff composition at boot, naming what is wrong and what to change. */
+function refuse(message, action, detail) {
+	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.
+*/
+function assertStaffComposition(staff, capabilities) {
+	if (!staff) return;
+	const tenancy = capabilities.find((candidate) => candidate.name === "organization");
+	const catalog = tenancy ? catalogOf(tenancy) : void 0;
+	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) : void 0;
+	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 !== void 0 && 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. */
+function staffMay(acting, staff, power) {
+	return acting !== null && staff !== void 0 && acting.roleAllows(staff[power]);
+}
+//#endregion
+export { assertStaffComposition, staffMay };

package/dist/store/assignment.d.ts

@@ -0,0 +1,63 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { D1Database } from "@cloudflare/workers-types";
+import { SupportAssignment, type SupportAssignmentActorType } from "../data/assignment";
+import { type SupportDatabase } from "../data/tables";
+import { SupportThread } from "../data/thread";
+/**
+ * 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;
+}
+/** Assign a thread, or unassign it. Throws `support/not_found` when it does not exist. */
+export declare function assignThread(d1: D1Database, options: AssignThreadOptions): Promise<AssignThreadResult>;
+/** A thread's assignee history, oldest first. */
+export declare function listAssignments(db: SupportDatabase, threadId: string): Promise<SupportAssignment[]>;
+//# sourceMappingURL=assignment.d.ts.map

package/dist/store/assignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignment.d.ts","sourceRoot":"","sources":["../../src/store/assignment.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAuB,MAAM,2BAA2B,CAAC;AAGjF,OAAO,EAAE,iBAAiB,EAAE,KAAK,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AACxF,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,oFAAoF;AACpF,MAAM,WAAW,QAAQ;IACvB,6FAA6F;IAC7F,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,kBAAkB;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,qCAAqC;IACrC,SAAS,EAAE,0BAA0B,CAAC;IACtC,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,WAAW;IACX,GAAG,EAAE,IAAI,CAAC;CACX;AAED,qCAAqC;AACrC,MAAM,WAAW,kBAAkB;IACjC,mCAAmC;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB,iGAAiG;IACjG,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC3B;AAiCD,0FAA0F;AAC1F,wBAAsB,YAAY,CAAC,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA6D5G;AAED,iDAAiD;AACjD,wBAAsB,eAAe,CAAC,EAAE,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAUzG"}

package/dist/store/assignment.js

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SupportNotFoundError } from "../error/errors.js";
+import { SupportAssignment } from "../data/assignment.js";
+import { SupportThread } from "../data/thread.js";
+import { SUPPORT_ASSIGNMENTS_TABLE, SUPPORT_THREADS_TABLE, supportDatabase } from "../data/tables.js";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { sql } from "kysely";
+//#region src/store/assignment.ts
+/** 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) {
+	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, compiled) {
+	return d1.prepare(compiled.sql).bind(...compiled.parameters);
+}
+/**
+* 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, row) {
+	const columns = Object.keys(row);
+	return db.insertInto(SUPPORT_ASSIGNMENTS_TABLE).columns(columns).expression(db.selectNoFrom(columns.map((column) => sql.val(row[column]).as(column))).where(sql`changes() > 0`)).compile();
+}
+/** Assign a thread, or unassign it. Throws `support/not_found` when it does not exist. */
+async function assignThread(d1, options) {
+	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);
+		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).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
+		}));
+		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. */
+async function listAssignments(db, threadId) {
+	return (await db.selectFrom(SUPPORT_ASSIGNMENTS_TABLE).selectAll().where("threadId", "=", threadId).orderBy("createdAt", "asc").orderBy(sql`rowid`, "asc").execute()).map((row) => SupportAssignment.parse(row));
+}
+//#endregion
+export { assignThread, listAssignments };

package/dist/store/hybrid.d.ts

@@ -0,0 +1,134 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Logger } from "@pithy-sh/core/src/logger/logger";
+import type { VectorIndexConfig } from "@pithy-sh/vector/src/config/config";
+import type { VectorAi } from "@pithy-sh/vector/src/embed/embed";
+import type { VectorStore } from "@pithy-sh/vector/src/index/index";
+import { type SupportDatabase } from "../data/tables";
+import { type KeywordBackend, type MessageHit } from "./search";
+import { type ListedThread, type ThreadFilters } from "./threads";
+/**
+ * Hybrid search — keyword and semantic, run together and ranked as one.
+ *
+ * The two fail in opposite directions. Keyword finds the exact string and misses the paraphrase; semantic
+ * finds the paraphrase and misses the identifier, because it cannot retrieve an order number it has never
+ * seen. A support inbox needs both.
+ *
+ * **Search is not listing.** A query goes in, ranked threads come out, up to a limit, and there is no cursor:
+ * a ranked list has a top, not pages.
+ *
+ * ## How a result is ranked
+ *
+ * 1. Each backend returns **messages**, best first — FTS5 by `bm25`, the `LIKE` scan by recency, Vectorize by
+ *    similarity.
+ * 2. Each list rolls up to **threads**: a thread takes the rank of its best message, and appears once.
+ * 3. Hybrid fuses the two thread lists by **reciprocal rank fusion** over rank position — `1 / (60 + rank)`,
+ *    summed. No weights to tune, and a thread both backends found rises above one only one found. The raw
+ *    scores are never normalized into one number: each result carries its message's `bm25` and similarity as
+ *    they were, absent where that backend did not run or did not match.
+ * 4. A tie goes to the keyword hit, the better keyword rank first, and then to `lastMessageAt`, newest first.
+ *    Semantic search cannot retrieve an identifier, so for a query like `ORD-40912` the exact match is keyword's
+ *    rank 1 while semantic's rank 1 is some other thread: equal fused scores, and the exact match wins.
+ *
+ * **Filters apply after retrieval, in D1**, never as Vectorize metadata, which would go stale the moment a
+ * thread is archived, reassigned or reclassified. A narrow filter can therefore return fewer than the limit,
+ * and the result's count says how many it did.
+ *
+ * **Degrade, never fail.** A backend that is on and cannot answer — FTS5 configured and its table not
+ * provisioned, the semantic index or its binding absent, a model that does not answer — is skipped and named,
+ * and the rest of the search still runs.
+ */
+/** The search modes a caller may ask for. */
+export type SearchMode = "keyword" | "semantic" | "hybrid";
+/** A backend that can answer part of a search. */
+export type SearchBackend = KeywordBackend | "semantic";
+/** Why a backend that is on did not answer. */
+export type SkipReason = "unprovisioned" | "failed";
+/** The reciprocal-rank-fusion constant — the standard 60, which damps the head without flattening it. */
+export declare const RRF_K = 60;
+/** How many messages each backend retrieves before the roll-up. Vectorize's payload-free ceiling. */
+export declare const SEARCH_HITS = 100;
+/** One thread a backend ranked, with the message that ranked it. */
+export interface RankedThread {
+    /** The thread. */
+    threadId: string;
+    /** Its best-matching message. */
+    messageId: string;
+    /** Its rank in this backend's list, 1 first. */
+    rank: number;
+}
+/**
+ * Roll a backend's message hits up to threads: a thread takes the rank of its best message, and appears once.
+ * The input is best first, so the first message seen for a thread is its best.
+ */
+export declare function rollUp(hits: readonly MessageHit[]): RankedThread[];
+/** One thread after fusion: its fused score and the message the result names. */
+export interface FusedThread {
+    /** The thread. */
+    threadId: string;
+    /** The message the result names — the one from the backend that ranked this thread higher. */
+    messageId: string;
+    /** The reciprocal-rank-fusion score. Internal: it orders results and is never reported. */
+    fused: number;
+}
+/**
+ * Fuse ranked thread lists by reciprocal rank fusion. A thread found by several lists sums its terms.
+ *
+ * The message a result names comes from the list that ranked the thread highest, the first list winning a
+ * tie — the keyword list is passed first, so an exact match names the message that holds it.
+ */
+export declare function fuse(lists: readonly (readonly RankedThread[])[]): FusedThread[];
+/** What a search asks. */
+export interface SearchThreadsQuery extends ThreadFilters {
+    /** The words. */
+    q: string;
+    /** Which backends to run. Absent runs every backend that is on. */
+    mode?: SearchMode;
+    /** How many threads to return. Defaults to {@link DEFAULT_SEARCH_LIMIT}, capped at {@link MAX_SEARCH_LIMIT}. */
+    limit?: number;
+}
+/** What a search needs. The semantic seams are absent exactly when that backend cannot run here. */
+export interface SearchDeps {
+    /** The support tables. */
+    db: SupportDatabase;
+    /** Whether `search.fts` is on. */
+    fts: boolean;
+    /** The message index, when `search.semantic` is on. */
+    index?: VectorIndexConfig;
+    /** The Workers AI binding, when bound. */
+    ai?: VectorAi;
+    /** The message index's Vectorize binding, when bound. */
+    store?: VectorStore;
+    /** The calling viewer — whose read and snooze state each result carries. */
+    viewer: string;
+    /** Where a skipped backend is reported to the operator. */
+    log?: Logger;
+}
+/** One search result: a thread, and the message that matched best with its raw scores. */
+export interface SearchResult {
+    /** The thread, as this viewer sees it. */
+    thread: ListedThread;
+    /** The best-matching message. */
+    messageId: string;
+    /** That message's FTS5 `bm25`, raw — lower is better. Absent when FTS5 did not run or did not match it. */
+    bm25?: number;
+    /** That message's similarity to the query, raw. Absent when semantic search did not run or did not match it. */
+    similarity?: number;
+}
+/** What a search did, and what it found. */
+export interface SearchOutcome {
+    /** The mode that ran — the one asked for, or `hybrid` when none was. */
+    mode: SearchMode;
+    /** The backends that answered. */
+    ran: SearchBackend[];
+    /** The backends that were on and could not answer, and why. */
+    skipped: {
+        backend: SearchBackend;
+        reason: SkipReason;
+    }[];
+    /** The threads, best first. */
+    results: SearchResult[];
+}
+/** Run a search. */
+export declare function searchThreads(deps: SearchDeps, query: SearchThreadsQuery): Promise<SearchOutcome>;
+//# sourceMappingURL=hybrid.d.ts.map

package/dist/store/hybrid.d.ts.map

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