@anchrd/intel-contract 0.27.0 → 0.29.0

package/dist/contract/board.d.ts

@@ -9,10 +9,23 @@ import { z } from "zod";
  * draws first.
  */
 export declare const ARCHIVE_COLUMN_ID = "archived";
+/**
+ * What a colour picker starts on for a column that has none (#725).
+ *
+ * ⚠️ **Here rather than in the browser package, and that is not tidiness.** The token linter refuses
+ * a hard-coded hex in `packages/ui`, and it is right to: a colour written into a component bypasses
+ * the theme. This one is not a theme colour, it is DATA — the value a person is about to choose
+ * from and the api writes as a default — so it belongs where both sides may read it, which is here.
+ *
+ * ⚠️ **It is the widget's starting point, never a written value.** `color` stays absent until
+ * somebody picks one, so opening the dialog does not repaint a board that predates colours.
+ */
+export declare const DEFAULT_COLUMN_COLOR = "#9ca3af";
 export declare const BoardColumn: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
     terminal: z.ZodDefault<z.ZodBoolean>;
+    color: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type BoardColumn = z.infer<typeof BoardColumn>;
 export declare const BoardTask: z.ZodObject<{
@@ -53,6 +66,7 @@ export declare const BoardView: z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
         terminal: z.ZodDefault<z.ZodBoolean>;
+        color: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     archiveVisible: z.ZodBoolean;
     tasks: z.ZodArray<z.ZodObject<{
@@ -76,6 +90,7 @@ export declare const BoardUpdateInput: z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
         terminal: z.ZodDefault<z.ZodBoolean>;
+        color: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     archiveVisible: z.ZodOptional<z.ZodBoolean>;
     idempotencyKey: z.ZodString;
@@ -130,5 +145,6 @@ export declare const BoardAssigneeList: z.ZodObject<{
         email: z.ZodEmail;
         isMachine: z.ZodBoolean;
     }, z.core.$strict>>;
+    more: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>;
 export type BoardAssigneeList = z.infer<typeof BoardAssigneeList>;

package/dist/contract/board.js

@@ -13,6 +13,18 @@ import { IdempotencyKey, IntelId, IsoDateTime } from "./contract.js";
  * draws first.
  */
 export const ARCHIVE_COLUMN_ID = "archived";
+/**
+ * What a colour picker starts on for a column that has none (#725).
+ *
+ * ⚠️ **Here rather than in the browser package, and that is not tidiness.** The token linter refuses
+ * a hard-coded hex in `packages/ui`, and it is right to: a colour written into a component bypasses
+ * the theme. This one is not a theme colour, it is DATA — the value a person is about to choose
+ * from and the api writes as a default — so it belongs where both sides may read it, which is here.
+ *
+ * ⚠️ **It is the widget's starting point, never a written value.** `color` stays absent until
+ * somebody picks one, so opening the dialog does not repaint a board that predates colours.
+ */
+export const DEFAULT_COLUMN_COLOR = "#9ca3af";
 export const BoardColumn = z.strictObject({
     id: z.string().min(1).max(60).describe("Stable key stored on every task in this column."),
     title: z.string().min(1).max(80).describe("What the column is called on screen."),
@@ -20,6 +32,20 @@ export const BoardColumn = z.strictObject({
         .boolean()
         .default(false)
         .describe("Whether a task in this column counts as finished. More than one column may be."),
+    /**
+     * ⚠️ **The colour belongs to the COLUMN, never to the card** (#725, and #365 took the status dot
+     * off the card on purpose). A card is in a column; drawing the column's colour on it would be the
+     * same fact twice, and the second copy is the one that goes stale.
+     *
+     * A free value rather than a fixed palette (Jack's decision 2026-08-22). It only ever fills a
+     * DOT, so a badly chosen one is hard to see but makes nothing unreadable — which is what makes a
+     * free choice affordable here and would not make it affordable behind text.
+     */
+    color: z
+        .string()
+        .regex(/^#[0-9a-fA-F]{6}$/, "A colour is six hex digits behind a hash, like #6b7280.")
+        .optional()
+        .describe("The dot in front of this column's title, and in front of a linked task that sits in it. Six hex digits behind a hash. Absent means the reader's own default, so an older board is not repainted by this field appearing."),
 });
 // One card, as the board view needs it: everything to draw and sort by, and NOTHING from R2. The
 // body is fetched per task through `node_version_get` when somebody opens one.
@@ -210,7 +236,7 @@ export const BoardAssigneeSearchInput = z.strictObject({
     boardId: IntelId.describe("The board whose people to offer. Only those who can open this board appear, so the same query against two boards can give two different answers."),
     query: z
         .string()
-        .describe("What was typed. Under two characters the answer is empty rather than everybody: a single letter is a listing under a different name."),
+        .describe("What was typed. EMPTY names up to three people who reach this board, so a picker can open with suggestions instead of nothing. One character answers empty rather than everybody: a single letter is a listing under a different name, while an empty query asks for a bounded set this board already knows."),
 });
 // ⚠️ A DIFFERENT question from the one above, and deliberately not board-scoped. This one names
 // people who are ALREADY recorded on a card, so that a circle can carry initials instead of a raw
@@ -223,4 +249,14 @@ export const BoardAssigneeResolveInput = z.strictObject({
         .max(100)
         .describe("The ids to name. Ids that cannot be named are absent from the answer rather than reported, and more than a hundred is refused rather than silently shortened."),
 });
-export const BoardAssigneeList = z.strictObject({ items: z.array(BoardAssignee) });
+export const BoardAssigneeList = z.strictObject({
+    items: z.array(BoardAssignee),
+    /**
+     * ⚠️ **How many are left over, so the cap is visible rather than silent** (#757). Three suggestions
+     * that look like the whole list are worse than three that say "and 4 more": the first teaches the
+     * reader that nobody else exists.
+     *
+     * `0` on a search answer, where the cap is gate's own and this door does not own it.
+     */
+    more: z.number().int().min(0).default(0),
+});

package/dist/contract/feed.d.ts

@@ -5,10 +5,26 @@ export declare const FeedAction: z.ZodEnum<{
     "node.update": "node.update";
     "node.append": "node.append";
     "node.archive": "node.archive";
+    "node.purge": "node.purge";
     "node.share": "node.share";
     "node.revoke": "node.revoke";
+    "flows.create": "flows.create";
+    "flows.save": "flows.save";
+    "flows.update": "flows.update";
+    "flows.publish": "flows.publish";
+    "flows.unpublish": "flows.unpublish";
+    "flows.archive": "flows.archive";
+    "flows.share": "flows.share";
+    "flows.revoke": "flows.revoke";
+    "flows.purge": "flows.purge";
 }>;
 export type FeedAction = z.infer<typeof FeedAction>;
+/**
+ * What an entry is about. Derived from the action rather than carried separately: the two can then
+ * never disagree, and a reader that has to draw a flow differently from a document does not depend
+ * on a second field being filled in correctly.
+ */
+export declare function feedKindOf(action: FeedAction): "node" | "flow";
 export declare const FeedPathSegment: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
@@ -23,11 +39,21 @@ export declare const FeedEvent: z.ZodObject<{
         "node.update": "node.update";
         "node.append": "node.append";
         "node.archive": "node.archive";
+        "node.purge": "node.purge";
         "node.share": "node.share";
         "node.revoke": "node.revoke";
+        "flows.create": "flows.create";
+        "flows.save": "flows.save";
+        "flows.update": "flows.update";
+        "flows.publish": "flows.publish";
+        "flows.unpublish": "flows.unpublish";
+        "flows.archive": "flows.archive";
+        "flows.share": "flows.share";
+        "flows.revoke": "flows.revoke";
+        "flows.purge": "flows.purge";
     }>;
-    nodeId: z.ZodString;
-    nodeTitle: z.ZodString;
+    resourceId: z.ZodString;
+    resourceTitle: z.ZodString;
     path: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
@@ -53,11 +79,21 @@ export declare const FeedListResponse: z.ZodObject<{
             "node.update": "node.update";
             "node.append": "node.append";
             "node.archive": "node.archive";
+            "node.purge": "node.purge";
             "node.share": "node.share";
             "node.revoke": "node.revoke";
+            "flows.create": "flows.create";
+            "flows.save": "flows.save";
+            "flows.update": "flows.update";
+            "flows.publish": "flows.publish";
+            "flows.unpublish": "flows.unpublish";
+            "flows.archive": "flows.archive";
+            "flows.share": "flows.share";
+            "flows.revoke": "flows.revoke";
+            "flows.purge": "flows.purge";
         }>;
-        nodeId: z.ZodString;
-        nodeTitle: z.ZodString;
+        resourceId: z.ZodString;
+        resourceTitle: z.ZodString;
         path: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             title: z.ZodString;

package/dist/contract/feed.js

@@ -16,9 +16,45 @@ export const FeedAction = z.enum([
     "node.update",
     "node.append",
     "node.archive",
+    // ⚠️ The one event whose node no longer exists when it is read. Its visibility runs over the
+    // surviving folder, from `parentId` in the metadata, and its title comes from there too — the row
+    // it would have been read from is gone (#645).
+    "node.purge",
     "node.share",
     "node.revoke",
+    // The flow half (#763). Twelve kinds are written; these are the ones a person did rather than a
+    // machine bookkeeping step.
+    //
+    // ⚠️ The three run kinds — `flows.run`, `flows.complete`, `flows.cancel` — are NOT here, and the
+    // reason is not that the list refuses them: they are written against `resource_type = 'flow-run'`
+    // with the RUN's id, which is a third kind this query does not read at all. Admitting them here
+    // would change nothing on the surface and quietly suggest they had been considered.
+    //
+    // They need their own everything — a third visibility walk (run → flow → folder), a title read
+    // from the flow rather than the run, a third link target — and one decision first: an agent
+    // writes three of them per run, so without any summarising a busy morning buries every human
+    // entry under identical cards. That is #767, and it is a real question rather than a leftover.
+    "flows.create",
+    "flows.save",
+    "flows.update",
+    "flows.publish",
+    "flows.unpublish",
+    "flows.archive",
+    "flows.share",
+    "flows.revoke",
+    // ⚠️ The flow-side twin of `node.purge`, and it carries the same two consequences: its row is
+    // gone when the card is read, so both its visibility and its title come from the metadata of the
+    // event itself (#763, D73).
+    "flows.purge",
 ]);
+/**
+ * What an entry is about. Derived from the action rather than carried separately: the two can then
+ * never disagree, and a reader that has to draw a flow differently from a document does not depend
+ * on a second field being filled in correctly.
+ */
+export function feedKindOf(action) {
+    return action.startsWith("flows.") ? "flow" : "node";
+}
 // One step on the way down to the node, from the root. It carries the id as well as the title
 // because the surface links each step, and two folders may share a name.
 export const FeedPathSegment = z.strictObject({
@@ -27,10 +63,14 @@ export const FeedPathSegment = z.strictObject({
 });
 // One card's worth of journal.
 //
-// ⚠️ `nodeTitle` and `path` are read from `nodes` at query time, so they are TODAY's title and
-// today's place — not the ones the node had when the event happened. That is the right answer for a
-// feed (the reader wants to find the thing now) and the wrong one for an audit trail, which is one
-// more reason these are two doors and not one.
+// ⚠️ `resourceTitle` and `path` are read from `nodes` or `flows` at query time, so they are TODAY's
+// title and today's place — not the ones the thing had when the event happened. That is the right
+// answer for a feed (the reader wants to find it now) and the wrong one for an audit trail, which is
+// one more reason these are two doors and not one.
+//
+// ⚠️ The fields say `resource` and not `node` because half of them are not nodes (#763). Which half
+// is answered by `feedKindOf(action)` and by nothing on the card — a second field saying "flow"
+// beside an action that already says `flows.publish` is a second truth, and two truths disagree.
 //
 // `metadata` is whatever the write site recorded, untyped on purpose: a schema per action would
 // have to be kept in step with eleven write sites and would go stale in silence. What the surface
@@ -40,8 +80,8 @@ export const FeedEvent = z.strictObject({
     id: IntelId,
     actorId: z.string().min(1),
     action: FeedAction,
-    nodeId: IntelId,
-    nodeTitle: z.string().min(1),
+    resourceId: IntelId,
+    resourceTitle: z.string().min(1),
     path: z.array(FeedPathSegment),
     metadata: z.record(z.string(), z.unknown()),
     occurredAt: IsoDateTime,

package/package.json

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