@anchrd/intel-api 0.35.0 → 0.36.0

package/dist/adapters/db/db-boards.js

@@ -247,6 +247,18 @@ export function createBoardRepository(deps) {
          * membership to anyone who can read it; what leaves this method cannot be turned back into who
          * granted what to whom.
          *
+         * ⚠️ **A grant can name an EMAIL instead of a user id, and both are real access** (#757). The
+         * first version of this counted only `principal_type = 'user'` and therefore showed nobody on a
+         * board shared by address. Measured on the installation on 2026-08-23: four of nine grants were
+         * `email` ones.
+         *
+         * ⚠️ **Not lowercased here, and that is measured rather than assumed.** The write path already
+         * normalises an address twice (`nodes.ts` before the write, `db-grants.ts` at the boundary), and
+         * the installation confirms it: every stored `email` grant is lowercase. A `lower()` here would
+         * be defence against data that cannot exist, and no test could tell it from a no-op. The side
+         * that DOES need folding is the directory hit, because gate stores what somebody typed at
+         * signup and its casing is not this repository's to decide.
+         *
          * ⚠️ `verb = 'read'`, and that is not a detail. The verbs here are granted INDEPENDENTLY
          * (ADR-0004 §2): `write` does not follow from `read` and `read` does not follow from `write`.
          * Counting any verb would offer somebody who holds only `write` or `share` as an assignee for a
@@ -279,17 +291,32 @@ export function createBoardRepository(deps) {
                  AND grant_row.verb = 'read'
                  AND ${grantInForce}
              )) AS principal_ids_json,
+            (SELECT json_group_array(principal_id)
+             FROM (
+               SELECT DISTINCT grant_row.principal_id
+               FROM node_grants grant_row
+               JOIN ancestors ON ancestors.id = grant_row.node_id
+               WHERE grant_row.principal_type = 'email'
+                 AND grant_row.principal_id IS NOT NULL
+                 AND grant_row.verb = 'read'
+                 AND ${grantInForce}
+             )) AS principal_emails_json,
             (SELECT COUNT(*)
              FROM node_grants grant_row
              JOIN ancestors ON ancestors.id = grant_row.node_id
              WHERE grant_row.principal_type = 'organization'
                AND grant_row.verb = 'read'
                AND ${grantInForce}) AS organization_grants`)
-                .bind(boardId, deps.now().toISOString(), deps.now().toISOString())
+                // ⚠️ ONE `now` per `grantInForce`, and there are three of them since #757: the user
+                // grants, the email grants and the organization count. A missing binding is not a wrong
+                // answer here, it is `D1_ERROR: Wrong number of parameter bindings` — loud, which is the
+                // good case. Read the count off the statement, never off memory.
+                .bind(boardId, deps.now().toISOString(), deps.now().toISOString(), deps.now().toISOString())
                 .first();
             return {
                 ownerIds: JSON.parse(row?.owner_ids_json ?? "[]"),
                 principalIds: JSON.parse(row?.principal_ids_json ?? "[]"),
+                principalEmails: JSON.parse(row?.principal_emails_json ?? "[]"),
                 organizationWide: (row?.organization_grants ?? 0) > 0,
             };
         },

package/dist/boards/boards.d.ts

@@ -9,22 +9,36 @@ import type { BoardDeps, BoardService } from "./boards.types.js";
  * and from then on they are data anybody can rename. This list only answers for a board nobody
  * configured — one made over MCP, or one whose seeding did not land.
  */
+/**
+ * ⚠️ **The four start coloured, and the colours mean something** (Jack's decision 2026-08-22): grey
+ * for what is only lying there, yellow for what is ready, orange for what is being worked on, green
+ * for what is done. That order is the one people already read without a legend, which is the whole
+ * reason a default is worth having — a board that starts grey teaches nothing, and one that starts
+ * in arbitrary colours teaches something false.
+ *
+ * They are a suggestion, not a setting: every one of them can be overwritten, and a board that has
+ * been recoloured keeps its own values.
+ */
 export declare const DEFAULT_COLUMNS: readonly [{
     readonly id: "backlog";
     readonly title: "Backlog";
     readonly terminal: false;
+    readonly color: "#9ca3af";
 }, {
     readonly id: "todo";
     readonly title: "Offen";
     readonly terminal: false;
+    readonly color: "#eab308";
 }, {
     readonly id: "doing";
     readonly title: "Läuft";
     readonly terminal: false;
+    readonly color: "#f97316";
 }, {
     readonly id: "done";
     readonly title: "Fertig";
     readonly terminal: true;
+    readonly color: "#22c55e";
 }];
 export declare const FIRST_DEFAULT_COLUMN: "backlog";
 export declare function createBoards(deps: BoardDeps): BoardService;

package/dist/boards/boards.js

@@ -1,4 +1,4 @@
-import { ARCHIVE_COLUMN_ID } from "@anchrd/intel-contract/board";
+import { ARCHIVE_COLUMN_ID, DEFAULT_COLUMN_COLOR } from "@anchrd/intel-contract/board";
 import { IntelError } from "../shared/intel-error/intel-error.js";
 /**
  * What a board with no configuration answers with. A board is usable the moment it is created, and
@@ -10,11 +10,21 @@ import { IntelError } from "../shared/intel-error/intel-error.js";
  * and from then on they are data anybody can rename. This list only answers for a board nobody
  * configured — one made over MCP, or one whose seeding did not land.
  */
+/**
+ * ⚠️ **The four start coloured, and the colours mean something** (Jack's decision 2026-08-22): grey
+ * for what is only lying there, yellow for what is ready, orange for what is being worked on, green
+ * for what is done. That order is the one people already read without a legend, which is the whole
+ * reason a default is worth having — a board that starts grey teaches nothing, and one that starts
+ * in arbitrary colours teaches something false.
+ *
+ * They are a suggestion, not a setting: every one of them can be overwritten, and a board that has
+ * been recoloured keeps its own values.
+ */
 export const DEFAULT_COLUMNS = [
-    { id: "backlog", title: "Backlog", terminal: false },
-    { id: "todo", title: "Offen", terminal: false },
-    { id: "doing", title: "Läuft", terminal: false },
-    { id: "done", title: "Fertig", terminal: true },
+    { id: "backlog", title: "Backlog", terminal: false, color: DEFAULT_COLUMN_COLOR },
+    { id: "todo", title: "Offen", terminal: false, color: "#eab308" },
+    { id: "doing", title: "Läuft", terminal: false, color: "#f97316" },
+    { id: "done", title: "Fertig", terminal: true, color: "#22c55e" },
 ];
 // The column a card lands in when nobody said and the board has none configured. One export rather
 // than the literal `"todo"` in three places: the fallback exists FOR the unconfigured board, so a
@@ -24,6 +34,26 @@ export const FIRST_DEFAULT_COLUMN = DEFAULT_COLUMNS[0].id;
 // is a listing under a different name — the same floor gate holds at its own door, stated here so
 // this surface keeps its own promise (#700).
 const MINIMUM_QUERY = 2;
+// How many people a picker offers before anybody types. Three is a suggestion, not a directory: a
+// longer list is one somebody reads instead of typing the name they already know (#757).
+const SUGGESTIONS = 3;
+/**
+ * Whether one person from the directory reaches this board (#700, #757).
+ *
+ * ⚠️ **Two ways in, and the second one cost a release to notice.** A grant names either a user id or
+ * an EMAIL, and both are real access. Counting only ids showed nobody on a board shared by address,
+ * which is how four of the nine grants on the reference installation are written.
+ *
+ * The address is compared lowercased on both sides: a grant written `Anton@…` and a directory hit
+ * that says `anton@…` are the same person, and a case-sensitive compare would quietly disagree.
+ */
+function reachedBy(access, person) {
+    if (access.ownerIds.includes(person.id))
+        return true;
+    if (access.principalIds.includes(person.id))
+        return true;
+    return access.principalEmails.includes(person.email.toLowerCase());
+}
 export function createBoards(deps) {
     /**
      * ⚠️ The one place "which board, and may this actor DO THIS to it" is answered — and the verb is
@@ -84,6 +114,61 @@ export function createBoards(deps) {
             return;
         throw new IntelError(400, "unknown_column", `This board has no column \`${status}\`. Its columns are: ${columns.join(", ")}.`);
     };
+    /**
+     * The people this board can be handed to, without a search term (#757).
+     *
+     * ⚠️ **Named, not enumerated.** Gate's directory answers searches, not listings, so what can be
+     * offered here is exactly the set this repository already knows by name: the owners, the user
+     * grants, and the addresses of the email grants. An organization-wide board therefore suggests
+     * whatever explicit grants it also has and nothing more — "everybody" is not a list anyone can
+     * produce, and pretending otherwise would mean asking gate to hand over its directory.
+     *
+     * ⚠️ **The cap is visible.** `more` says how many are left over, so the picker can say "and 4
+     * more" instead of quietly showing three and looking complete.
+     */
+    const suggest = async (boardId) => {
+        if (!deps.directory)
+            return { items: [], more: 0 };
+        const access = await deps.boards.effectiveAccess(boardId);
+        const ids = [...new Set([...access.ownerIds, ...access.principalIds])];
+        // One call for every id at once. The addresses need one lookup each, because gate resolves ids
+        // and searches text and there is no third door — so only as many as it takes to FILL the cap.
+        const byId = ids.length === 0 ? [] : await deps.directory.resolve(ids);
+        const knownEmails = new Set(byId.map((person) => person.email.toLowerCase()));
+        /**
+         * ⚠️ **The count and the list are two different things, and the count comes FIRST.**
+         *
+         * An earlier version stopped looking after the cap and then reported the leftovers it happened
+         * to have — so a board with ten address grants said "and 1 more" instead of "and 7 more". The
+         * cap was visible and its number was wrong, which is worse than no number: it is a number
+         * somebody believes.
+         *
+         * Counted here without naming anybody: every address that is not already one of the resolved
+         * people is one more person who reaches this board. Whether gate can name them does not change
+         * how many there are.
+         */
+        const unnamedAddresses = access.principalEmails.filter((address) => !knownEmails.has(address));
+        const total = byId.length + unnamedAddresses.length;
+        /**
+         * ⚠️ **The cap counts LOOKUPS, not names found**, and the difference is a real hole. An address
+         * gate cannot name never grows `named`, so a bound on the names would never trigger: a board
+         * with a hundred address grants and no matching accounts would fire a hundred sequential calls
+         * to gate to open one menu. The test that sets six unnameable addresses walks exactly that path.
+         */
+        const named = [...byId];
+        let lookups = 0;
+        for (const address of unnamedAddresses) {
+            if (named.length >= SUGGESTIONS || lookups >= SUGGESTIONS)
+                break;
+            lookups += 1;
+            const found = await deps.directory.search(address);
+            const exact = found.find((person) => person.email.toLowerCase() === address);
+            if (exact !== undefined)
+                named.push(exact);
+        }
+        const items = named.slice(0, SUGGESTIONS);
+        return { items, more: Math.max(0, total - items.length) };
+    };
     return {
         async get(actor, input) {
             return await viewOrRefuse(actor, input);
@@ -308,7 +393,7 @@ export function createBoards(deps) {
             // read gives, so a board one may not see stays indistinguishable from one that is not there.
             await columnsOrRefuse(actor, input.boardId, "read");
             if (!deps.directory)
-                return { items: [] };
+                return { items: [], more: 0 };
             /**
              * ⚠️ ENFORCED HERE, not only described. The contract's `query` says a single character
              * answers empty, and until this line that sentence was true only because gate happens to
@@ -317,19 +402,31 @@ export function createBoards(deps) {
              * It is also the cheaper answer: a letter that can only ever produce a listing does not
              * need to travel to gate first to be refused there.
              */
-            if (input.query.trim().length < MINIMUM_QUERY)
-                return { items: [] };
-            const hits = await deps.directory.search(input.query);
+            const query = input.query.trim();
+            /**
+             * ⚠️ **Nothing typed is a QUESTION, not a refusal** (#757). The set of people who reach this
+             * board is short and known, so it can be named without a search term — and a picker that
+             * opens empty teaches the reader that there is nobody, which is the opposite of what it
+             * means.
+             *
+             * A single character stays refused, and the reason is unchanged: a letter is not a search, it
+             * is a listing under a different name. The two cases differ because one names a bounded set
+             * and the other asks the directory to filter one.
+             */
+            if (query.length === 0)
+                return await suggest(input.boardId);
+            if (query.length < MINIMUM_QUERY)
+                return { items: [], more: 0 };
+            const hits = await deps.directory.search(query);
             if (hits.length === 0)
-                return { items: [] };
+                return { items: [], more: 0 };
             const access = await deps.boards.effectiveAccess(input.boardId);
             // A grant to the organization means everybody reaches the board, so there is nothing left to
             // narrow — and narrowing anyway would produce an empty picker on exactly the boards that are
             // shared with everyone, which is most of them.
             if (access.organizationWide)
-                return { items: hits };
-            const reaches = new Set([...access.ownerIds, ...access.principalIds]);
-            return { items: hits.filter((hit) => reaches.has(hit.id)) };
+                return { items: hits, more: 0 };
+            return { items: hits.filter((hit) => reachedBy(access, hit)), more: 0 };
         },
         /**
          * What the people already recorded on cards are called (#258, #700).

package/dist/boards/boards.types.d.ts

@@ -56,6 +56,7 @@ export interface BoardRepository {
     effectiveAccess(boardId: string): Promise<{
         ownerIds: string[];
         principalIds: string[];
+        principalEmails: string[];
         organizationWide: boolean;
     }>;
 }
@@ -101,8 +102,14 @@ export interface BoardService {
     update(actor: Actor, input: BoardUpdateInput): Promise<BoardView>;
     createTask(actor: Actor, input: BoardTaskCreateInput): Promise<BoardView>;
     updateTask(actor: Actor, input: BoardTaskUpdateInput): Promise<BoardView>;
+    /**
+     * ⚠️ `more` says how many people reach this board beyond the ones named, so a capped list can say
+     * so instead of looking complete (#757). It is `0` on a search answer, where the cap belongs to
+     * gate and not to this door.
+     */
     searchAssignees(actor: Actor, input: BoardAssigneeSearchInput): Promise<{
         items: BoardAssignee[];
+        more: number;
     }>;
     resolveAssignees(actor: Actor, input: BoardAssigneeResolveInput): Promise<{
         items: BoardAssignee[];

package/dist/mcp/mcp.js

@@ -192,7 +192,7 @@ export async function handleMcp(request, deps) {
         // `list`, and a filter does not change which verb a call is.
         server.registerTool("board_assignee_list", {
             title: "Who a card on this board can be given to",
-            description: "Find the people you may set as assignee on a card of this board, by typing part of a name or an address. Only people who can actually open THIS board are offered, so the same query against two boards can give two different answers. Under two characters the answer is empty rather than everybody. Use board_assignee_resolve to name somebody already on a card.",
+            description: "Find the people you may set as assignee on a card of this board. Only people who can actually open THIS board are offered, so the same query against two boards can give two different answers. Leave the query EMPTY to get up to three of them without searching, plus a count of how many more there are. One character answers empty rather than everybody; from two on it filters. Use board_assignee_resolve to name somebody already on a card.",
             inputSchema: BoardAssigneeSearchInput,
             annotations: {
                 title: "Who a card on this board can be given to",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.25.0",
-    "@anchrd/intel-contract": "^0.27.0",
+    "@anchrd/intel-contract": "^0.28.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",