@anchrd/intel 0.59.0

package/dist/boards/boards.js

@@ -0,0 +1,447 @@
+import { ARCHIVE_COLUMN_ID, DEFAULT_COLUMN_COLOR } from "../contract/board.js";
+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
+ * nothing asks whoever made it to define columns before filing the first card.
+ *
+ * ⚠️ **This is the FALLBACK, not what a board made through the application gets.** Columns are
+ * shared data: two people on one board must read the same names, and the settings dialog edits one
+ * list. So the application writes them at creation, in the language of whoever created it (#675),
+ * 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, 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
+// copy of it would drift exactly where it is the only thing deciding.
+export const FIRST_DEFAULT_COLUMN = DEFAULT_COLUMNS[0].id;
+// Below this a query answers empty rather than with everybody. A single letter is not a search, it
+// 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
+     * the whole question. It asked `read` for every caller once, including the three that were about
+     * to write: a board shared read-only could have its columns replaced and its cards moved. The
+     * refusal existed and asked the wrong thing, which is the harder failure to see.
+     *
+     * A `404` rather than a `403`, on purpose: "this board exists but you may not touch it" is itself
+     * information about somebody else's tree.
+     */
+    const columnsOrRefuse = async (actor, boardId, verb) => {
+        const columns = await deps.boards.columnsOf(actor, boardId, verb);
+        if (columns === null) {
+            throw new IntelError(404, "board_not_found", "No board with this id is readable for you.");
+        }
+        return columns.length > 0 ? columns : DEFAULT_COLUMNS.map((column) => column.id);
+    };
+    const viewOrRefuse = async (actor, input) => {
+        const view = await deps.boards.read(actor, input);
+        if (view === null) {
+            throw new IntelError(404, "board_not_found", "No board with this id is readable for you.");
+        }
+        // A board that was never configured answers with the default columns rather than none. An empty
+        // column list would render as a board with no columns at all — a screen with nowhere to put a
+        // card, which looks broken rather than new.
+        /**
+         * ⚠️ **A stored column may not claim the archive id, and the migration is not the only guard.**
+         * `0024` renames the ones that existed before the id was reserved, and `update` refuses new
+         * ones — but a row written straight into D1, or a migration that did not reach an installation,
+         * would still put two columns with one id in front of a reader. Dropping it here means the
+         * derived one always wins, which is the answer that cannot produce two.
+         */
+        const configured = (view.columns.length > 0 ? view.columns : [...DEFAULT_COLUMNS]).filter((column) => column.id !== ARCHIVE_COLUMN_ID);
+        /**
+         * ⚠️ **The archive column is appended here, after the fallback, and it is never stored.** A
+         * card is in it because `nodes.archived_at` is set; `board_tasks.status` keeps naming the
+         * working column underneath, which is what a card pulled back out returns to (D68).
+         *
+         * Always last, and not part of the list `board_update` writes: the archive is the same place on
+         * every board. A shelf that could be dragged between the working columns would be a shelf
+         * pretending to be a stage.
+         *
+         * ⚠️ **The title here is a fallback, not the label a reader sees.** Configured columns are
+         * shared data and are therefore written once in the creator's language (#675); this one is
+         * derived and identical on every board, so the browser says it in the reader's own words
+         * (`useBoard`). What travels is English, for everything without a catalog — MCP, an export, a
+         * report.
+         */
+        return {
+            ...view,
+            columns: view.archiveVisible
+                ? [...configured, { id: ARCHIVE_COLUMN_ID, title: "Archive", terminal: true }]
+                : configured,
+        };
+    };
+    const requireColumn = (columns, status) => {
+        if (columns.includes(status))
+            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);
+        },
+        async update(actor, input) {
+            await columnsOrRefuse(actor, input.boardId, "write");
+            // ⚠️ Duplicate ids are refused rather than deduplicated. Two columns with one id means every
+            // card in them lands in whichever the view draws first, and silently dropping one would
+            // discard a column somebody just wrote.
+            const ids = input.columns.map((column) => column.id);
+            const duplicate = ids.find((id, index) => ids.indexOf(id) !== index);
+            if (duplicate !== undefined) {
+                throw new IntelError(400, "duplicate_column", `The column id \`${duplicate}\` appears more than once.`);
+            }
+            /**
+             * ⚠️ **The archive id cannot be claimed by a configured column.** It is derived — a card is in
+             * it because `archived_at` is set — so a stored column of the same id would give a board two
+             * columns with one id: every card in them lands in whichever the view draws first, and one of
+             * the two can never receive a card at all.
+             */
+            /**
+             * ⚠️ **Duplicate NAMES are refused here, not only in the dialog.** An id nobody sees may
+             * repeat without confusing anybody; a name is what a person reads, and two columns called the
+             * same thing cannot be told apart on the board, in the filter, or in the settings. Checked in
+             * the service because an agent calling `board_update` reaches no dialog — root `CLAUDE.md`:
+             * validation does not vary by surface.
+             */
+            const titles = input.columns.map((column) => column.title.trim());
+            const duplicateTitle = titles.find((title, index) => titles.indexOf(title) !== index);
+            if (duplicateTitle !== undefined) {
+                throw new IntelError(400, "duplicate_column_name", `Two columns are called \`${duplicateTitle}\`. A name is what tells them apart.`);
+            }
+            if (ids.includes(ARCHIVE_COLUMN_ID)) {
+                throw new IntelError(400, "reserved_column", `\`${ARCHIVE_COLUMN_ID}\` is the archive column, which every board has. Show or hide it instead of configuring it.`);
+            }
+            await deps.boards.setColumns(input.boardId, JSON.stringify(input.columns), deps.now().toISOString(), input.archiveVisible);
+            return await viewOrRefuse(actor, { boardId: input.boardId, includeArchived: false });
+        },
+        async createTask(actor, input) {
+            const columns = await columnsOrRefuse(actor, input.boardId, "write");
+            // Absent means the first column — a caller who does not care where a task starts should not
+            // have to read the board first. A named one is checked, because a typo would otherwise create
+            // a card in a column no view draws.
+            const status = input.status ?? columns[0] ?? DEFAULT_COLUMNS[0].id;
+            if (input.status !== undefined)
+                requireColumn(columns, status);
+            /**
+             * ⚠️ **The parent's board must BE the board that was asked for**, checked here rather than
+             * left to the node path. `nodes.create` resolves the destination board from the parent, and
+             * on creation there is no previous board to compare it with — so a call naming board B with a
+             * parent on board A files the card on **A**, answers with the view of **B**, and the caller
+             * gets neither an error nor their card. The position would have been counted against B too.
+             */
+            if (input.parentTaskId !== null) {
+                // ⚠️ `"write"` for the same reason `attachToBoard` uses it — filing a card here is a write
+                // to that board. It is defence in depth rather than the only guard: `nodes.create` checks
+                // `write` on the parent node itself and answers 403 first, which is why a behaviour test
+                // cannot tell `"read"` from `"write"` here. Named so the next reader does not go looking
+                // for the test that proves it.
+                const parentRow = await deps.boards.taskRow(actor, input.parentTaskId, "write");
+                /**
+                 * ⚠️ **Only the wrong BOARD is refused here.** `taskRow` answers `null` for three different
+                 * things — the node does not exist, it is not a task, or this actor may not write it — and
+                 * each of those already has a precise answer further in: `404 node_not_found` from
+                 * `requireVisible`, `task_belongs_to_a_board` from `refuseWrongParent`, `403` from the
+                 * write check. Catching them here would answer "that parent card is not on this board" for
+                 * a card that does not exist, which claims it does.
+                 */
+                if (parentRow !== null && parentRow.boardId !== input.boardId) {
+                    throw new IntelError(409, "task_cannot_change_board", "That parent card is not on this board. A subtask belongs to the same board as the card it hangs under.");
+                }
+            }
+            // ⚠️ Through the node service, not a second insert. The task gets the same authorization
+            // check, the same audit row and the same version chain every other node gets — and that audit
+            // row is what `anchrd/signals` reads (#620).
+            const node = await deps.nodes.create(actor, {
+                // ⚠️ A subtask's parent is the TASK, not the board — the hierarchy is the node tree (#669).
+                // The node service resolves which board that lands on and files the row there, so nothing
+                // here has to know: naming the board as parent would flatten every subtask on creation.
+                parentId: input.parentTaskId ?? input.boardId,
+                kind: "task",
+                title: input.title,
+                description: null,
+                idempotencyKey: input.idempotencyKey,
+            });
+            /**
+             * ⚠️ **`update`, not `attach` — the row already exists by the time this line runs**, and
+             * getting that wrong is silent. `nodes.create` files every new task through `attachToBoard`,
+             * with the board's first column and no fields; a second `INSERT` here is refused by the
+             * primary key, `ON CONFLICT DO NOTHING` swallows the refusal, and the caller's `status`,
+             * assignee and dates are **discarded without an error**. The card lands in the wrong column
+             * and nothing anywhere says why.
+             *
+             * It was written as an insert first, and three tests caught it: a card created in `doing`
+             * came back in `todo`. The lesson is the shape rather than the line — one row, one writer,
+             * and the writer is the node path.
+             */
+            /**
+             * ⚠️ **The position is computed only when the card is not already in that column**, and that
+             * is what makes a retry safe. `deps.nodes.create` honours the idempotency key and answers with
+             * the SAME node on a replay; recomputing here would push the card one place further on every
+             * attempt — a client retrying a timeout would watch its card walk down the column, with every
+             * call succeeding.
+             *
+             * The other fields are rewritten with the same values, which is idempotent by construction.
+             */
+            const filed = await deps.boards.taskRow(actor, node.id, "write");
+            await deps.boards.updateTask(node.id, {
+                status,
+                assignee_id: input.assigneeId,
+                labels_json: JSON.stringify(input.labels),
+                start_date: input.startDate,
+                due_date: input.dueDate,
+                depends_on: input.dependsOn,
+                ...(filed?.status === status
+                    ? {}
+                    : { position: await deps.boards.nextPosition(input.boardId, status) }),
+            }, deps.now().toISOString());
+            return await viewOrRefuse(actor, { boardId: input.boardId, includeArchived: false });
+        },
+        async updateTask(actor, input) {
+            const row = await deps.boards.taskRow(actor, input.taskId, "write");
+            if (row === null) {
+                throw new IntelError(404, "task_not_found", "No task with this id is readable for you.");
+            }
+            /**
+             * ⚠️ **Dropping a card on the archive column archives it; pulling it out restores it** (D68).
+             * Neither writes `board_tasks.status`: the working column underneath is what a restored card
+             * returns to, and overwriting it with `archived` would be the second stored truth this
+             * design exists against.
+             *
+             * `nodes.archive` is the same door `node_archive` uses — one path, one audit row, one set of
+             * refusals. ⚠️ Since D71 (#733) that door CASCADES: dropping a card with subtasks on the
+             * archive column takes them with it, where #669 used to refuse the drop. Pulling the card back
+             * out brings exactly those back, and pulling a SUBTASK out while its parent card is archived
+             * is refused instead — a live card under an archived one is what the purge reaches.
+             */
+            const intoArchive = input.status === ARCHIVE_COLUMN_ID;
+            const outOfArchive = input.status !== undefined && !intoArchive && row.archivedAt !== null;
+            if (intoArchive || outOfArchive) {
+                await deps.nodes.archive(actor, {
+                    nodeId: input.taskId,
+                    baseUpdatedAt: row.updatedAt,
+                    archived: intoArchive,
+                    idempotencyKey: `${input.idempotencyKey}:archive`,
+                });
+            }
+            if (input.status !== undefined && !intoArchive) {
+                requireColumn(await columnsOrRefuse(actor, row.boardId, "write"), input.status);
+            }
+            // Only what arrived. An absent field means "leave it"; `null` where the column is nullable
+            // means "clear it", which is why the check is against `undefined` and not against falsiness —
+            // `dueDate: null` and `position: 0` both have to get through.
+            const fields = {};
+            if (input.title !== undefined) {
+                // ⚠️ The title lives on the NODE, not here. `board_tasks` has no title column, and adding
+                // one would make two rows disagree about what a card is called.
+                throw new IntelError(400, "title_belongs_to_the_node", "Rename a task with `node_update`; the board row carries no title.");
+            }
+            // ⚠️ Not for a drop into the archive: the working column stays as it is, so the card knows
+            // where to go back to.
+            if (input.status !== undefined && !intoArchive)
+                fields.status = input.status;
+            // ⚠️ Not for a drop into the archive either. The kanban sends a position with EVERY drop,
+            // computed from the neighbours inside the column it was dropped on — and inside the archive
+            // those are cards from all over the board. Taken, it would overwrite the card's place in the
+            // working column with a number that means nothing there. The status is guarded one line up;
+            // without this line the guard only covered half the write.
+            if (input.position !== undefined && !intoArchive)
+                fields.position = input.position;
+            if (input.assigneeId !== undefined)
+                fields.assignee_id = input.assigneeId;
+            if (input.labels !== undefined)
+                fields.labels_json = JSON.stringify(input.labels);
+            if (input.startDate !== undefined)
+                fields.start_date = input.startDate;
+            if (input.dueDate !== undefined)
+                fields.due_date = input.dueDate;
+            if (input.dependsOn !== undefined)
+                fields.depends_on = input.dependsOn;
+            /**
+             * A move that names a new column but no position lands at the end of it — otherwise the card
+             * would keep the number it had in its old column and appear at an arbitrary place.
+             *
+             * ⚠️ **Only when the column actually CHANGES.** Asking again for the column a card is already
+             * in is what a retry looks like, and recomputing there would move the card one place further
+             * on every attempt while every call reported success. That is the idempotency the tool
+             * promises with `idempotentHint: true`, kept by construction rather than by a key lookup.
+             */
+            /**
+             * ⚠️ **Never for a drop into the archive**, and the reason is the same one that keeps
+             * `fields.status` unset there: `board_tasks.status` never holds `archived`, so
+             * `nextPosition(board, "archived")` counts zero rows and answers `1` — every time. The card
+             * keeps its working column but silently loses its place IN it, landing first among cards it
+             * used to sit behind. Nothing reports that, and the reader only sees it after restoring.
+             */
+            if (input.status !== undefined &&
+                input.position === undefined &&
+                row.status !== input.status &&
+                !intoArchive) {
+                fields.position = await deps.boards.nextPosition(row.boardId, input.status);
+            }
+            if (Object.keys(fields).length > 0) {
+                await deps.boards.updateTask(input.taskId, fields, deps.now().toISOString());
+            }
+            return await viewOrRefuse(actor, { boardId: row.boardId, includeArchived: false });
+        },
+        /**
+         * Who this card may be given to (D70, #700).
+         *
+         * ⚠️ THE ANSWER IS NARROWER THAN GATE'S, NEVER WIDER. gate is asked first and its hits are then
+         * dropped down to the people who can actually open this board. That order is what makes the
+         * door safe to offer to anyone who can read the board: whatever survives the filter, gate would
+         * have handed the same person anyway at its own `POST /directory/search`.
+         *
+         * The reverse order would have been the leak: asking the board first and then naming the
+         * principals would hand out a membership list for a board to anyone who can see it.
+         */
+        async searchAssignees(actor, input) {
+            // `read`, not `share`: offering an assignee is something everyone who can open the board
+            // does, while managing grants is not. The 404 from here is the same one every other board
+            // 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: [], 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
+             * hold the same floor — a promise this repository made and a different service kept.
+             *
+             * 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.
+             */
+            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: [], 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, more: 0 };
+            return { items: hits.filter((hit) => reachedBy(access, hit)), more: 0 };
+        },
+        /**
+         * What the people already recorded on cards are called (#258, #700).
+         *
+         * ⚠️ NOT narrowed by the board, and that is the difference from the search above. Someone whose
+         * grant was withdrawn, or whose account was switched off, is still the person this card was
+         * given to. Filtering them out would leave the card reading as unassigned, which is a worse
+         * answer than the truth — and it would not protect anything, because the caller already holds
+         * the id and got it from a card they may read.
+         */
+        async resolveNames(actor, input) {
+            void actor;
+            if (!deps.directory)
+                return { items: [] };
+            return { items: await deps.directory.resolve(input.ids) };
+        },
+    };
+}

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

@@ -0,0 +1,117 @@
+import type { BoardAssigneeSearchInput, BoardGetInput, BoardTaskCreateInput, BoardTaskUpdateInput, BoardUpdateInput, BoardView, DirectoryPerson, DirectoryResolveInput } from "../contract/board.js";
+import type { Node } from "../contract/node.js";
+import type { Actor } from "../nodes/nodes.types.js";
+export type { BoardView };
+export interface BoardTaskRow {
+    nodeId: string;
+    boardId: string;
+    status: string;
+    position: number;
+    /**
+     * From the NODE, not from `board_tasks` (D68, #674).
+     *
+     * ⚠️ Whether a card is archived is `nodes.archived_at` and nothing else. The row carries it so
+     * that a move can tell "into the archive" from "out of it" without a second read — and so that
+     * nobody is tempted to store the answer here, which would be the two truths D68 exists against.
+     */
+    archivedAt: string | null;
+    updatedAt: string;
+}
+export interface BoardTaskWrite {
+    nodeId: string;
+    boardId: string;
+    status: string;
+    assigneeId: string | null;
+    labels: string[];
+    startDate: string | null;
+    dueDate: string | null;
+    dependsOn: string | null;
+    position: number;
+    occurredAt: string;
+}
+export interface BoardRepository {
+    read(actor: Actor, input: BoardGetInput): Promise<BoardView | null>;
+    columnsOf(actor: Actor, boardId: string, verb: "read" | "write"): Promise<string[] | null>;
+    /**
+     * ⚠️ `archiveVisible` is `undefined` for "leave it as it is" — the dialog that writes the columns
+     * and the switch that hides the archive are the same call, and a caller who only reorders columns
+     * must not silently un-hide an archive somebody put away.
+     */
+    setColumns(boardId: string, columnsJson: string, occurredAt: string, archiveVisible?: boolean): Promise<void>;
+    attach(write: BoardTaskWrite): Promise<void>;
+    taskRow(actor: Actor, taskId: string, verb: "read" | "write"): Promise<BoardTaskRow | null>;
+    updateTask(taskId: string, fields: Record<string, string | number | null>, occurredAt: string): Promise<void>;
+    nextPosition(boardId: string, status: string): Promise<number>;
+    /**
+     * Who reaches this node once inheritance is resolved: every grant along the folders above plus
+     * the owners. The same answer `listEffectiveAccess` gives, reached through the SAME repository
+     * method, so the two can never disagree about who has access.
+     *
+     * ⚠️ Read here WITHOUT the `share` permission the application-level `listEffectiveAccess`
+     * demands, and that is deliberate rather than an oversight. The two callers ask for different
+     * reasons: managing sharing is an owner's job, while naming the people a card may be given to is
+     * something anyone who can open the board has to be able to do. The answer never leaves this
+     * service as a list of grants; it is only ever used to NARROW what gate already offers.
+     */
+    effectiveAccess(boardId: string): Promise<{
+        ownerIds: string[];
+        principalIds: string[];
+        principalEmails: string[];
+        organizationWide: boolean;
+    }>;
+}
+/**
+ * The one seam to gate's directory, built PER REQUEST around the caller's bearer.
+ *
+ * ⚠️ The bearer never reaches this service, and it must not: `Actor` is the resolved identity, not
+ * the credential that produced it. The edge already holds the token because it just authorized with
+ * it, so it closes over it here and hands in something that answers questions instead.
+ */
+export interface DirectoryPort {
+    search(query: string): Promise<DirectoryPerson[]>;
+    resolve(ids: string[]): Promise<DirectoryPerson[]>;
+}
+export interface BoardNodePort {
+    create(actor: Actor, input: {
+        parentId: string;
+        kind: "task";
+        title: string;
+        description: null;
+        idempotencyKey: string;
+    }): Promise<Node>;
+    /**
+     * ⚠️ The same door `node_archive` uses. Dropping a card on the archive column must not become a
+     * second way to archive: one path means one audit row, one set of refusals — a card with live
+     * subtasks stays refused (#669) — and one answer to "what does archived mean".
+     */
+    archive(actor: Actor, input: {
+        nodeId: string;
+        baseUpdatedAt: string;
+        archived: boolean;
+        idempotencyKey: string;
+    }): Promise<Node>;
+}
+export interface BoardDeps {
+    boards: BoardRepository;
+    nodes: BoardNodePort;
+    now(): Date;
+    directory?: DirectoryPort;
+}
+export interface BoardService {
+    get(actor: Actor, input: BoardGetInput): Promise<BoardView>;
+    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: DirectoryPerson[];
+        more: number;
+    }>;
+    resolveNames(actor: Actor, input: DirectoryResolveInput): Promise<{
+        items: DirectoryPerson[];
+    }>;
+}

package/dist/boards/boards.types.js

@@ -0,0 +1 @@
+export {};

package/dist/build/build.d.ts

@@ -0,0 +1,2 @@
+import type { BuildDeps, BuildResult } from "./build.types.js";
+export declare function createBuild(deps: BuildDeps): BuildResult;