@anchrd/intel-contract 0.10.0 → 0.11.0

package/dist/contract/contract.d.ts

@@ -471,6 +471,7 @@ export declare const BoardStatus: z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
     order: z.ZodNumber;
+    terminal: z.ZodBoolean;
 }, z.core.$strict>;
 export type BoardStatus = z.infer<typeof BoardStatus>;
 export declare const BoardDefaultStatuses: readonly BoardStatus[];
@@ -502,6 +503,45 @@ export declare const BoardTaskId: z.ZodString;
 export declare const BoardTaskLabel: z.ZodString;
 export declare const BoardTaskDate: z.ZodISODate;
 export declare const BoardTaskDescription: z.ZodString;
+/**
+ * The tasks one task waits for (#285), each of them at most once (anchrd/intel#318).
+ *
+ * ⚠️ Board-internal only, enforced on the write path: a dependency on a task in another board would
+ * hang this node on a file that can change without anyone here noticing. Across boards the link is
+ * `references`, which points at the board NODE and lands in the link graph.
+ *
+ * ⚠️ Refused rather than folded together, the same shape as the status ids in `ConfigureBoardInput`.
+ * A repeat carries no information — but that is a fact about the value, not about the answer: a
+ * caller handed back a shorter list than it sent is told nothing, and composes the same one again.
+ * The refusal names the mistake once, and the caller is holding the list it has to fix. (The one
+ * place a repeat is folded instead is `upgradeStoredBoard`, where there is no caller to tell.)
+ *
+ * ⚠️ It sits on the STORED task as well as on the two inputs, so a consumer may rely on it rather
+ * than defend against it — `createBoardGraph` mints one edge key per pair, and a second one threw
+ * the whole graph view off the screen for everybody looking at that board.
+ */
+export declare const BoardTaskDependsOn: z.ZodArray<z.ZodString>;
+/**
+ * A task's labels, each of them at most once (anchrd/intel#318).
+ *
+ * ⚠️ The same rule the detail panel has always applied to what a person types — it refuses to add a
+ * label the task already carries — stated where every surface meets it, because the MCP write path
+ * did not. A repeated label draws the same chip twice on the card, with two remove buttons of which
+ * either takes both away, and weights that word higher in the search text (`indexing.ts`).
+ */
+export declare const BoardTaskLabels: z.ZodArray<z.ZodString>;
+/**
+ * The Intel nodes a task points at, each of them at most once (anchrd/intel#318).
+ *
+ * They land in the link graph as `text` links, the same way a document's inline links do, so what a
+ * board points at is visible from the other side too.
+ *
+ * ⚠️ Distinct for the same reason as `labels`: the picker in the detail panel already refuses one
+ * the task holds, and the link graph counts a repeat once anyway (`ON CONFLICT DO NOTHING`), so a
+ * duplicate is a second row in the panel and nothing else — which is exactly the kind of value that
+ * has no reading and should not be storable.
+ */
+export declare const BoardTaskReferences: z.ZodArray<z.ZodString>;
 export declare const BoardTask: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
@@ -528,6 +568,7 @@ export declare const BoardDocument: z.ZodObject<{
         id: z.ZodString;
         label: z.ZodString;
         order: z.ZodNumber;
+        terminal: z.ZodBoolean;
     }, z.core.$strict>>;
     tasks: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -581,6 +622,7 @@ export declare const NodeBoard: z.ZodObject<{
             id: z.ZodString;
             label: z.ZodString;
             order: z.ZodNumber;
+            terminal: z.ZodBoolean;
         }, z.core.$strict>>;
         tasks: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -609,6 +651,7 @@ export type NodeBoard = z.infer<typeof NodeBoard>;
 export declare const BoardStatusInput: z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
+    terminal: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type BoardStatusInput = z.infer<typeof BoardStatusInput>;
 export declare const ConfigureBoardInput: z.ZodObject<{
@@ -616,6 +659,7 @@ export declare const ConfigureBoardInput: z.ZodObject<{
     statuses: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         label: z.ZodString;
+        terminal: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     idempotencyKey: z.ZodString;
 }, z.core.$strict>;
@@ -829,6 +873,7 @@ export declare const ConfigureBoardResult: z.ZodObject<{
         id: z.ZodString;
         label: z.ZodString;
         order: z.ZodNumber;
+        terminal: z.ZodBoolean;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type ConfigureBoardResult = z.infer<typeof ConfigureBoardResult>;
@@ -1761,6 +1806,7 @@ export declare const ToolCatalog: z.ZodObject<{
         }, z.core.$strict>;
         fingerprint: z.ZodString;
     }, z.core.$strict>>;
+    reached: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type ToolCatalog = z.infer<typeof ToolCatalog>;
 /**

package/dist/contract/contract.js

@@ -291,14 +291,32 @@ export const BoardStatus = z.strictObject({
     // both claiming position 3 is a board no surface could draw, and it is a state nobody has to be
     // able to reason about if it cannot be expressed.
     order: z.number().int().nonnegative(),
+    /**
+     * Whether standing in this column means the work is finished (anchrd/intel#311).
+     *
+     * It answers the one question #285 left open — when a `dependsOn` is satisfied — and it is the
+     * ONLY answer to it. There is deliberately no second reading anywhere: a surface that decided
+     * "done" for itself would decide it differently the first time somebody reconfigured a board.
+     *
+     * ⚠️ It is a property of the status, not a position in the list, and that distinction is the
+     * whole ticket. #286 first read "the last column before `archived`" as done, reasoning by symmetry
+     * with the server's rule that a new task lands in the first column that is not `archived`. But a
+     * status list is configurable on purpose, so `… done → blocked → archived` makes "blocked" mean
+     * finished — silently, with a wrong blocked marker as the only symptom.
+     *
+     * ⚠️ Several columns may carry it. "Done" and a cancelled-like column are both ends of the work,
+     * and nothing waiting on a cancelled task is still blocked by it.
+     */
+    terminal: z.boolean(),
 });
 // What a board starts out with. Five columns, of which the last one is the fixed `archived` shelf.
+// `done` and the shelf are where work ends; the three before them are not (anchrd/intel#311).
 export const BoardDefaultStatuses = [
-    { id: "backlog", label: "Backlog", order: 0 },
-    { id: "in_progress", label: "In progress", order: 1 },
-    { id: "review", label: "Review", order: 2 },
-    { id: "done", label: "Done", order: 3 },
-    { id: ArchivedBoardStatusId, label: "Archived", order: 4 },
+    { id: "backlog", label: "Backlog", order: 0, terminal: false },
+    { id: "in_progress", label: "In progress", order: 1, terminal: false },
+    { id: "review", label: "Review", order: 2, terminal: false },
+    { id: "done", label: "Done", order: 3, terminal: true },
+    { id: ArchivedBoardStatusId, label: "Archived", order: 4, terminal: true },
 ];
 /**
  * Who a task is on: a person Gate knows, or an agent node in this installation (#285).
@@ -328,27 +346,76 @@ export const BoardTaskDate = z.iso.date();
 // Markdown, and capped: a task's description is a card, and what needs more than this is a document
 // the task can point at through `references`.
 export const BoardTaskDescription = z.string().max(20_000);
+/**
+ * The tasks one task waits for (#285), each of them at most once (anchrd/intel#318).
+ *
+ * ⚠️ Board-internal only, enforced on the write path: a dependency on a task in another board would
+ * hang this node on a file that can change without anyone here noticing. Across boards the link is
+ * `references`, which points at the board NODE and lands in the link graph.
+ *
+ * ⚠️ Refused rather than folded together, the same shape as the status ids in `ConfigureBoardInput`.
+ * A repeat carries no information — but that is a fact about the value, not about the answer: a
+ * caller handed back a shorter list than it sent is told nothing, and composes the same one again.
+ * The refusal names the mistake once, and the caller is holding the list it has to fix. (The one
+ * place a repeat is folded instead is `upgradeStoredBoard`, where there is no caller to tell.)
+ *
+ * ⚠️ It sits on the STORED task as well as on the two inputs, so a consumer may rely on it rather
+ * than defend against it — `createBoardGraph` mints one edge key per pair, and a second one threw
+ * the whole graph view off the screen for everybody looking at that board.
+ */
+export const BoardTaskDependsOn = z
+    .array(BoardTaskId)
+    .max(64)
+    .refine((ids) => new Set(ids).size === ids.length, {
+    error: "A task can be named only once in dependsOn",
+});
+/**
+ * A task's labels, each of them at most once (anchrd/intel#318).
+ *
+ * ⚠️ The same rule the detail panel has always applied to what a person types — it refuses to add a
+ * label the task already carries — stated where every surface meets it, because the MCP write path
+ * did not. A repeated label draws the same chip twice on the card, with two remove buttons of which
+ * either takes both away, and weights that word higher in the search text (`indexing.ts`).
+ */
+export const BoardTaskLabels = z
+    .array(BoardTaskLabel)
+    .max(32)
+    .refine((labels) => new Set(labels).size === labels.length, {
+    error: "A label can be named only once",
+});
+/**
+ * The Intel nodes a task points at, each of them at most once (anchrd/intel#318).
+ *
+ * They land in the link graph as `text` links, the same way a document's inline links do, so what a
+ * board points at is visible from the other side too.
+ *
+ * ⚠️ Distinct for the same reason as `labels`: the picker in the detail panel already refuses one
+ * the task holds, and the link graph counts a repeat once anyway (`ON CONFLICT DO NOTHING`), so a
+ * duplicate is a second row in the panel and nothing else — which is exactly the kind of value that
+ * has no reading and should not be storable.
+ */
+export const BoardTaskReferences = z
+    .array(IntelId)
+    .max(64)
+    .refine((ids) => new Set(ids).size === ids.length, {
+    error: "A node can be referenced only once",
+});
 export const BoardTask = z.strictObject({
     id: BoardTaskId,
     title: z.string().trim().min(1).max(240),
     status: BoardStatusId,
     assignee: BoardAssignee.nullable(),
-    labels: z.array(BoardTaskLabel).max(32),
+    labels: BoardTaskLabels,
     startDate: BoardTaskDate.nullable(),
     dueDate: BoardTaskDate.nullable(),
     // ⚠️ The whole hierarchy in one field, deliberately: epic, task and subtask are a DEPTH and not a
     // type (#285). A `kind` beside it would allow a subtask under nothing and an epic under an epic,
     // and every surface would then need its own opinion about which combinations mean anything.
     parentId: BoardTaskId.nullable(),
-    // ⚠️ Board-internal only, enforced on the write path: a dependency on a task in another board
-    // would hang this node on a file that can change without anyone here noticing. Across boards the
-    // link is `references`, which points at the board NODE and lands in the link graph.
-    dependsOn: z.array(BoardTaskId).max(64),
+    dependsOn: BoardTaskDependsOn,
     order: BoardTaskOrder,
     description: BoardTaskDescription,
-    // Node ids. They land in the link graph as `text` links, the same way a document's inline links
-    // do, so what a board points at is visible from the other side too.
-    references: z.array(IntelId).max(64),
+    references: BoardTaskReferences,
 });
 // The whole board, as it is stored and as it is read. There is no second representation to keep in
 // step with it — this document is the file.
@@ -370,6 +437,16 @@ export const NodeBoard = z.strictObject({
 export const BoardStatusInput = z.strictObject({
     id: BoardStatusId,
     label: z.string().trim().min(1).max(60),
+    /**
+     * Whether this column means finished (anchrd/intel#311).
+     *
+     * ⚠️ Optional, and the absence is not the same as `false`. A caller who says nothing gets the
+     * server's answer — `false` for an ordinary column, `true` for the shelf, which cannot be
+     * anything else. Making it a required boolean would force every caller that only wanted to rename
+     * a column to restate the whole board's notion of done, and getting one entry wrong there is a
+     * silent change to what counts as blocked.
+     */
+    terminal: z.boolean().optional(),
 });
 // The status list, written whole and in the order it should be drawn — never a patch. Adding,
 // renaming and reordering are all this one call, and `archived` has to be in what it is given.
@@ -384,7 +461,12 @@ export const ConfigureBoardInput = z.strictObject({
     })
         .refine((statuses) => statuses.some((status) => status.id === ArchivedBoardStatusId), {
         error: `The "${ArchivedBoardStatusId}" status cannot be removed`,
-    }),
+    })
+        // ⚠️ Refused rather than corrected, the same way removing the shelf is refused. A task swept
+        // onto `archived` is finished with, and a board that could declare the shelf non-terminal would
+        // hold every archived task open as a blocker forever. Only an EXPLICIT `false` is refused —
+        // saying nothing is fine and means the server's `true` (anchrd/intel#311).
+        .refine((statuses) => statuses.find((status) => status.id === ArchivedBoardStatusId)?.terminal !== false, { error: `The "${ArchivedBoardStatusId}" status is always terminal` }),
     idempotencyKey: z.string().min(8).max(200),
 });
 /**
@@ -402,13 +484,13 @@ export const AddBoardTaskInput = z.strictObject({
     // the shelf.
     status: BoardStatusId.optional(),
     assignee: BoardAssignee.nullable().default(null),
-    labels: z.array(BoardTaskLabel).max(32).default([]),
+    labels: BoardTaskLabels.default([]),
     startDate: BoardTaskDate.nullable().default(null),
     dueDate: BoardTaskDate.nullable().default(null),
     parentId: BoardTaskId.nullable().default(null),
-    dependsOn: z.array(BoardTaskId).max(64).default([]),
+    dependsOn: BoardTaskDependsOn.default([]),
     description: BoardTaskDescription.default(""),
-    references: z.array(IntelId).max(64).default([]),
+    references: BoardTaskReferences.default([]),
     // Where among its neighbours it goes. Both absent puts it last in its column.
     afterTaskId: BoardTaskId.nullable().default(null),
     beforeTaskId: BoardTaskId.nullable().default(null),
@@ -428,12 +510,12 @@ export const UpdateBoardTaskInput = z
     taskId: BoardTaskId,
     title: z.string().trim().min(1).max(240).optional(),
     assignee: BoardAssignee.nullable().optional(),
-    labels: z.array(BoardTaskLabel).max(32).optional(),
+    labels: BoardTaskLabels.optional(),
     startDate: BoardTaskDate.nullable().optional(),
     dueDate: BoardTaskDate.nullable().optional(),
-    dependsOn: z.array(BoardTaskId).max(64).optional(),
+    dependsOn: BoardTaskDependsOn.optional(),
     description: BoardTaskDescription.optional(),
-    references: z.array(IntelId).max(64).optional(),
+    references: BoardTaskReferences.optional(),
     idempotencyKey: z.string().min(8).max(200),
 })
     .refine((input) => input.title !== undefined ||
@@ -1030,6 +1112,24 @@ export const ToolCapability = z.strictObject({
 export const ToolCatalog = z.strictObject({
     portalConnected: z.boolean(),
     items: z.array(ToolCapability),
+    /**
+     * Which delegated servers actually contributed a tool to this catalog (#289).
+     *
+     * ⚠️ Present only where the attribution was actually made — a delegated caller whose catalog was
+     * read. It is absent for an ordinary user, and absent as well when the answer comes from one of
+     * the short paths that never reach the portal (nothing delegated, no portal sign-in, connection
+     * dropped). Absent therefore means "not stated", never "nothing arrived"; `[]` is the second one.
+     *
+     * That it is missing rather than empty on those paths is deliberate rather than half-finished:
+     * the attribution already happens for a delegation — `capabilities` has to make it to cut the
+     * list — so naming it costs nothing there, while computing the same thing for an ordinary user
+     * would mean a second portal request per call, for a question their screen does not ask.
+     *
+     * ⚠️ It is the answer to "what arrived", never to "what was granted". A server missing here has
+     * been switched off, revoked, or is failing right now; the delegation in the definition is
+     * unchanged. Reading it the other way round would turn an outage into a permission change.
+     */
+    reached: z.array(ToolServerHandle).optional(),
 });
 /**
  * One MCP server the asking user reaches right now, as the portal itself names it (D30).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-contract",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {