@anchrd/intel 0.59.0

package/dist/contract/board.js

@@ -0,0 +1,262 @@
+import { z } from "zod";
+import { IdempotencyKey, IntelId, IsoDateTime } from "./contract.js";
+// One column of a board. `terminal` is what "done" means here — a rule about the column rather than
+// a magic status name, so an installation may call it "Shipped" or "Abgerechnet" without anything
+// downstream having to know the word.
+/**
+ * The id of the archive column, on every board (D68, #674).
+ *
+ * ⚠️ **It is derived, never stored.** A card sits in it because `nodes.archived_at` is set, and
+ * `board_tasks.status` keeps naming the working column it came from — that is what lets a card
+ * pulled back out land where it was. A configured column may not claim this id; `board_update`
+ * refuses it, because two columns with one id means every card in them lands in whichever the view
+ * 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/intel/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."),
+    terminal: z
+        .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.
+//
+// ⚠️ `position` is a float, not an index. Dropping a card between two neighbours is then the
+// midpoint of the two, and no other row is written. With integers every drop would renumber
+// everything below it, and two people dropping at once would fight over rows neither touched.
+export const BoardTask = z.strictObject({
+    id: IntelId.describe("The card's node id — its address everywhere else in Intel."),
+    title: z.string().min(1).max(240).describe("What the card says."),
+    status: z.string().min(1).max(60).describe("Which column it sits in."),
+    assigneeId: z.string().min(1).nullable(),
+    labels: z.array(z.string().min(1).max(40)),
+    startDate: IsoDateTime.nullable(),
+    dueDate: IsoDateTime.nullable(),
+    dependsOn: IntelId.nullable(),
+    /**
+     * The task this one sits under, or `null` when it sits directly on the board.
+     *
+     * ⚠️ **The hierarchy is the node tree** (`nodes.parent_id`), not a second column here — a task
+     * under a task IS the tree Intel already has, which is why the cycle guard that refuses moving a
+     * node into its own descendant covers this for free.
+     *
+     * ⚠️ **Under a filter this may name a task that is not in the same answer.** `board_get` returns
+     * what matches; a subtask can match while its parent does not. A reader that assumes the parent
+     * is present will lose the row — treat an unknown parent as top level.
+     */
+    parentTaskId: IntelId.nullable(),
+    position: z.number(),
+    archivedAt: IsoDateTime.nullable(),
+});
+// ⚠️ Every filter here is a COLUMN in `board_tasks`, and that is the whole reason the fields are not
+// in the body. A filter the application applies after reading has already fetched the rows — over
+// the wire, into memory, past the point where leaving them out would have helped.
+export const BoardTaskFilter = z.strictObject({
+    status: z
+        .string()
+        .min(1)
+        .max(60)
+        .optional()
+        .describe("Only tasks in this column. Omit for every column."),
+    assigneeId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Only tasks assigned to this Gate principal. An agent is not a special case here."),
+    dueBefore: IsoDateTime.optional().describe("Only tasks due strictly before this moment. Tasks without a due date never match."),
+    dependsOn: IntelId.optional().describe("Only tasks waiting for this node — what `board_get` answers when you ask what one thing blocks."),
+    includeArchived: z
+        .boolean()
+        .default(false)
+        .describe("Include archived tasks beside the live ones instead of hiding them."),
+});
+export const BoardGetInput = BoardTaskFilter.extend({
+    boardId: IntelId.describe("The board node to read. Must be a node of kind `board`."),
+});
+// One answer for the whole board, not one per card.
+export const BoardView = z.strictObject({
+    boardId: IntelId,
+    title: z.string().min(1).max(240),
+    columns: z.array(BoardColumn),
+    /**
+     * Whether the archive column is drawn (D68, #674).
+     *
+     * ⚠️ It travels even when it is `false`, because the settings dialog needs to draw the switch in
+     * both positions — and because "the column is not in `columns`" has two possible reasons, hidden
+     * and not-yet-supported, which a reader cannot tell apart from the list alone.
+     */
+    archiveVisible: z.boolean(),
+    tasks: z.array(BoardTask),
+});
+export const BoardUpdateInput = z.strictObject({
+    boardId: IntelId.describe("The board node whose columns are being set."),
+    columns: z
+        .array(BoardColumn)
+        .min(1)
+        .describe(`The complete new column list, in order. Columns are replaced, not merged. The archive column (\`${ARCHIVE_COLUMN_ID}\`) is not part of this list and cannot be named in it — it is on every board and is only shown or hidden.`),
+    // ⚠️ Shown or hidden, never removed. 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.
+    archiveVisible: z
+        .boolean()
+        .optional()
+        .describe("Whether the archive column is drawn. Omit to leave it as it is."),
+    idempotencyKey: IdempotencyKey,
+});
+export const BoardTaskCreateInput = z.strictObject({
+    boardId: IntelId.describe("The board the task is filed under. It becomes the task's parent."),
+    title: z.string().min(1).max(240).describe("What the card says on the board."),
+    // ⚠️ Optional, and absent means the FIRST column rather than an error. A caller who does not care
+    // where a task starts should not have to read the board first — and a task with no status would
+    // be a card no view can draw.
+    status: z
+        .string()
+        .min(1)
+        .max(60)
+        .optional()
+        .describe("Which column to file it in. Omit for the board's first column."),
+    assigneeId: z
+        .string()
+        .min(1)
+        .nullable()
+        .default(null)
+        .describe("Who it is for, as a Gate principal id. An agent is not a special case."),
+    labels: z
+        .array(z.string().min(1).max(40))
+        .default([])
+        .describe("Free-form tags. They are filtered on the board, not in search."),
+    startDate: IsoDateTime.nullable()
+        .default(null)
+        .describe("When work on it should begin. Only the timeline view draws it."),
+    dueDate: IsoDateTime.nullable()
+        .default(null)
+        .describe("When it is due. A card without one never matches a due-before filter."),
+    dependsOn: IntelId.nullable()
+        .default(null)
+        .describe("A node this task waits for. Any node, not only another task."),
+    // ⚠️ Creating a subtask is ONE call; moving an existing task under another is `node_update`
+    // with a new `parentId`. Two paths for "where a task sits" would mean two cycle guards, and the
+    // one on the node path is the one that already exists.
+    parentTaskId: IntelId.nullable()
+        .default(null)
+        .describe("The task this one belongs under. It must be on the same board. Omit for a card that sits directly on the board."),
+    idempotencyKey: IdempotencyKey,
+});
+// ⚠️ Moving a card IS this call: `status` and `position` together. There is deliberately no
+// `board_task_move` — it would be a second way to write one row, and a model reading `tools/list`
+// would have to guess which of the two applies.
+//
+// Every field is optional and absent means "leave it": a drag sends two fields, a rename sends one.
+// `null` is a value where the column is nullable, so clearing a due date is `dueDate: null` and not
+// its absence.
+export const BoardTaskUpdateInput = z.strictObject({
+    taskId: IntelId.describe("The card to change, by its node id."),
+    title: z
+        .string()
+        .min(1)
+        .max(240)
+        .optional()
+        .describe("Refused on purpose: a card's title lives on the node. Rename it with node_update."),
+    status: z
+        .string()
+        .min(1)
+        .max(60)
+        .optional()
+        .describe(`The column to move it to. \`${ARCHIVE_COLUMN_ID}\` is not an ordinary column: it archives the card through the same path as \`node_archive\`, with the same refusals — a card that still has live subtasks is refused. Moving it to any other column while it is archived brings it back.`),
+    position: z
+        .number()
+        .optional()
+        .describe("Where in the column. Use the midpoint between the two neighbours it lands between."),
+    assigneeId: z
+        .string()
+        .min(1)
+        .nullable()
+        .optional()
+        .describe("Who it is for. `null` unassigns it; leaving it out keeps whoever has it."),
+    labels: z
+        .array(z.string().min(1).max(40))
+        .optional()
+        .describe("The complete new tag list. Tags are replaced, not merged."),
+    startDate: IsoDateTime.nullable()
+        .optional()
+        .describe("When work should begin. `null` clears it."),
+    dueDate: IsoDateTime.nullable().optional().describe("When it is due. `null` clears it."),
+    dependsOn: IntelId.nullable()
+        .optional()
+        .describe("A node this card waits for. `null` clears the dependency."),
+    idempotencyKey: IdempotencyKey,
+});
+// ── Who a card can be given to ────────────────────────────────────────────────────────────────
+// D70 (`~/Dev/anchrd/core/DECISIONS.md`): the people offered here are the ones who can actually open
+// THIS board, never everyone who holds an account. The narrower answer is the point, and it is what
+// makes the door safe to offer to anyone who can see the board.
+//
+// ⚠️ `email` travels because two colleagues share a first name more often than a picker can afford,
+// and a list of indistinguishable "Anton" rows is not a picker. It is no wider than what gate hands
+// any signed-in person at `POST /directory/search`; the narrowing this door adds is WHO appears,
+// not WHAT is said about them.
+//
+// `isMachine` travels for the same reason gate carries it: whoever picks an assignee wants to know
+// whether they are handing the card to a colleague or to an agent.
+export const DirectoryPerson = z.strictObject({
+    id: IntelId,
+    name: z.string(),
+    email: z.email(),
+    isMachine: z.boolean(),
+});
+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. 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
+// id (`#258`). Someone whose access was withdrawn, or whose account was switched off, still has to
+// be nameable: a card that reads as unassigned is a worse answer than the truth.
+export const DirectoryResolveInput = z.strictObject({
+    ids: z
+        .array(IntelId)
+        .min(1)
+        .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 DirectoryPersonList = z.strictObject({
+    items: z.array(DirectoryPerson),
+    /**
+     * ⚠️ **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/bundle.d.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+export declare const BundleManifestFilename = "manifest.json";
+/**
+ * What a bundle entry can be. `flow` joins the node kinds because a flow shares the folder tree
+ * without being a node (ADR-0004), and the bundle mirrors the tree, not the tables.
+ *
+ * ⚠️ `agent` and `board` are STILL HERE, and that is the one place in this file where a value
+ * survives its feature (#390). A bundle is somebody else's file: an export written before Agents
+ * and Board were parked (#385) is a correct export, and it has to PARSE so the import can refuse it
+ * by name — with the entry, the kind and the branch the code is on. Take them out and the same
+ * bundle fails as `unexpected enum value`, which sends its holder looking for a broken file that is
+ * not broken.
+ *
+ * They belong to the wire format of a file that already exists, not to the product. Nothing may
+ * create either kind; `NodeKind` is the enum that says so.
+ */
+export declare const BundleEntryKind: z.ZodEnum<{
+    folder: "folder";
+    document: "document";
+    attachment: "attachment";
+    table: "table";
+    board: "board";
+    flow: "flow";
+    agent: "agent";
+}>;
+export type BundleEntryKind = z.infer<typeof BundleEntryKind>;
+/**
+ * Why an entry carries no bytes although its kind normally does (#534).
+ *
+ * `no-content` is a node that has never been given any: a table created but never defined has no
+ * version, and an attachment created but never uploaded has none either, so there is nothing to
+ * write. That is a different sentence from "the content is gone", which the export refuses as
+ * `content_missing` — and a file of zero bytes cannot say which of the two it is, which is exactly
+ * what it used to do.
+ */
+export declare const BundleEntryAbsence: z.ZodEnum<{
+    "no-content": "no-content";
+}>;
+export type BundleEntryAbsence = z.infer<typeof BundleEntryAbsence>;
+export declare const BundleManifestEntry: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        folder: "folder";
+        document: "document";
+        attachment: "attachment";
+        table: "table";
+        board: "board";
+        flow: "flow";
+        agent: "agent";
+    }>;
+    title: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    mediaType: z.ZodNullable<z.ZodString>;
+    path: z.ZodString;
+    absence: z.ZodOptional<z.ZodEnum<{
+        "no-content": "no-content";
+    }>>;
+}, z.core.$strict>;
+export type BundleManifestEntry = z.infer<typeof BundleManifestEntry>;
+/**
+ * What an export leaves out on purpose, named so a bundle says it rather than a reader guessing:
+ * version history, grants/shares, flow runs, and archived nodes are not in any bundle (#136).
+ *
+ * ⚠️ `unpublished-flow-changes` is the FIFTH, and it is the one exception to ADR-0006's own
+ * headline (#585). A bundle carries the current state of everything — except a flow that has been
+ * published, which travels as its PUBLISHED graph. Edits made after that publication are in no
+ * bundle, and they are not history: they are the newest state there is. The word exists because the
+ * loss is only acceptable while it is named, and `version-history` does not name it — a reader who
+ * saw only that word would expect the newest graph and get one that is deliberately older.
+ *
+ * ⚠️ These are WIRE values: an older reader refuses a bundle naming an exclusion it does not know,
+ * the same way it would refuse an unknown `kind`. The enum grows only for something an installation
+ * genuinely leaves behind, never as a place to note a nicety (ADR-0006, #433). Growing it costs the
+ * direction nobody migrates in — a bundle written HERE is refused by an installation older than
+ * this line, while every bundle written before it still parses, which is the direction 0.22.0's
+ * rebuild actually runs.
+ */
+export declare const BundleExclusion: z.ZodEnum<{
+    "version-history": "version-history";
+    grants: "grants";
+    "flow-runs": "flow-runs";
+    "archived-nodes": "archived-nodes";
+    "unpublished-flow-changes": "unpublished-flow-changes";
+}>;
+export type BundleExclusion = z.infer<typeof BundleExclusion>;
+export declare const BundleManifest: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    exportedAt: z.ZodISODateTime;
+    rootId: z.ZodNullable<z.ZodString>;
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            folder: "folder";
+            document: "document";
+            attachment: "attachment";
+            table: "table";
+            board: "board";
+            flow: "flow";
+            agent: "agent";
+        }>;
+        title: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        mediaType: z.ZodNullable<z.ZodString>;
+        path: z.ZodString;
+        absence: z.ZodOptional<z.ZodEnum<{
+            "no-content": "no-content";
+        }>>;
+    }, z.core.$strict>>;
+    excluded: z.ZodArray<z.ZodEnum<{
+        "version-history": "version-history";
+        grants: "grants";
+        "flow-runs": "flow-runs";
+        "archived-nodes": "archived-nodes";
+        "unpublished-flow-changes": "unpublished-flow-changes";
+    }>>;
+}, z.core.$strict>;
+export type BundleManifest = z.infer<typeof BundleManifest>;
+/**
+ * What one import made. Import always creates new nodes — no merge, no overwrite, no restored IDs
+ * (#137, phase 1) — so the answer is counts and the new roots, never a diff. `replayed` marks the
+ * idempotent second answer to the same key: nothing was created twice.
+ *
+ * ⚠️ `excluded` is what the IMPORT knows about itself, never what the bundle claimed (ADR-0006,
+ * #433). A subtree moved between installations arrives with one version per node, no grants and no
+ * runs, and until now nothing said so at the moment somebody could still act on it — the word stood
+ * only in a `manifest.json` inside the zip that had already been written.
+ *
+ * It is deliberately NOT read back out of that manifest. A hand-written bundle saying `excluded: []`
+ * would then make the import report that nothing was left behind, and the import would launder
+ * somebody else's claim into an answer that sounds like its own — the trap `absence` is bound
+ * against in `BundleManifestEntry` above (#534, #560). The five exclusions hold for every import
+ * this build performs, with a manifest or from a naked folder, so this is a constant of the code.
+ */
+export declare const BundleImportResult: z.ZodObject<{
+    nodes: z.ZodNumber;
+    flows: z.ZodNumber;
+    rootNodeIds: z.ZodArray<z.ZodString>;
+    replayed: z.ZodBoolean;
+    excluded: z.ZodArray<z.ZodEnum<{
+        "version-history": "version-history";
+        grants: "grants";
+        "flow-runs": "flow-runs";
+        "archived-nodes": "archived-nodes";
+        "unpublished-flow-changes": "unpublished-flow-changes";
+    }>>;
+}, z.core.$strict>;
+export type BundleImportResult = z.infer<typeof BundleImportResult>;

package/dist/contract/bundle.js

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { IntelId, IsoDateTime } from "./contract.js";
+// ── Bundle export (#136) ────────────────────────────────────────────────────────────────────────
+// The one name the importer looks for at the zip root. A different spelling would make a bundle a
+// naked folder, so the constant lives in the contract rather than in each surface.
+export const BundleManifestFilename = "manifest.json";
+/**
+ * What a bundle entry can be. `flow` joins the node kinds because a flow shares the folder tree
+ * without being a node (ADR-0004), and the bundle mirrors the tree, not the tables.
+ *
+ * ⚠️ `agent` and `board` are STILL HERE, and that is the one place in this file where a value
+ * survives its feature (#390). A bundle is somebody else's file: an export written before Agents
+ * and Board were parked (#385) is a correct export, and it has to PARSE so the import can refuse it
+ * by name — with the entry, the kind and the branch the code is on. Take them out and the same
+ * bundle fails as `unexpected enum value`, which sends its holder looking for a broken file that is
+ * not broken.
+ *
+ * They belong to the wire format of a file that already exists, not to the product. Nothing may
+ * create either kind; `NodeKind` is the enum that says so.
+ */
+export const BundleEntryKind = z.enum([
+    "folder",
+    "document",
+    "table",
+    "attachment",
+    "agent",
+    "board",
+    "flow",
+]);
+/**
+ * Why an entry carries no bytes although its kind normally does (#534).
+ *
+ * `no-content` is a node that has never been given any: a table created but never defined has no
+ * version, and an attachment created but never uploaded has none either, so there is nothing to
+ * write. That is a different sentence from "the content is gone", which the export refuses as
+ * `content_missing` — and a file of zero bytes cannot say which of the two it is, which is exactly
+ * what it used to do.
+ */
+export const BundleEntryAbsence = z.enum(["no-content"]);
+// One entry of the manifest: the identity a re-import needs, next to the relative path where the
+// bytes sit in the zip. A folder carries no media type — it has no bytes.
+export const BundleManifestEntry = z
+    .strictObject({
+    id: IntelId,
+    kind: BundleEntryKind,
+    title: z.string().min(1).max(240),
+    description: z.string().max(2_000).nullable(),
+    mediaType: z.string().min(1).max(160).nullable(),
+    // Relative to the zip root, forward slashes, no leading slash. Folders end with a slash so an
+    // empty folder still has an address. An entry with an `absence` keeps its path even though no
+    // file sits there: the path is what puts the node in the tree on the way back in.
+    path: z.string().min(1).max(4_000),
+    // ⚠️ OPTIONAL rather than nullable, and that is about files that already exist. This object is
+    // strict, so a required key would refuse every bundle written before #534 with
+    // `import_invalid_manifest` — a whole format broken over a word that only ever describes a node
+    // with nothing in it. Absent means the entry has its file, which is what every older bundle
+    // means.
+    absence: BundleEntryAbsence.optional(),
+})
+    /**
+     * ⚠️ Only a table or an attachment may declare an absence, and the guard belongs HERE rather
+     * than at the import.
+     *
+     * A bundle is somebody else's file, and the import reads this word as permission to skip the
+     * check that a manifest entry has its file in the zip. Left unrestricted, an entry saying
+     * `kind: "document"` with `absence: "no-content"` would walk past that check even when the file
+     * IS in the zip — and the document would be created empty, silently, with nothing refused.
+     *
+     * The two kinds named here are the ones whose canonical content is the whole of them: a table
+     * IS its CSV and an attachment IS its bytes, so for them "no content" is a state of the node
+     * rather than a claim about a file. A document without a version is a different case and stays
+     * out — an empty markdown file says the same thing about it without ambiguity (#534, #560).
+     *
+     * Refusing at the boundary is the difference between a named refusal and lost content: the
+     * import validates this schema before it plans anything, so a manifest like that fails as
+     * `import_invalid_manifest` instead of importing something the bundle does not say.
+     */
+    .refine((entry) => entry.absence === undefined || entry.kind === "table" || entry.kind === "attachment", {
+    message: "Only a table or attachment entry may declare an absence",
+    path: ["absence"],
+});
+/**
+ * What an export leaves out on purpose, named so a bundle says it rather than a reader guessing:
+ * version history, grants/shares, flow runs, and archived nodes are not in any bundle (#136).
+ *
+ * ⚠️ `unpublished-flow-changes` is the FIFTH, and it is the one exception to ADR-0006's own
+ * headline (#585). A bundle carries the current state of everything — except a flow that has been
+ * published, which travels as its PUBLISHED graph. Edits made after that publication are in no
+ * bundle, and they are not history: they are the newest state there is. The word exists because the
+ * loss is only acceptable while it is named, and `version-history` does not name it — a reader who
+ * saw only that word would expect the newest graph and get one that is deliberately older.
+ *
+ * ⚠️ These are WIRE values: an older reader refuses a bundle naming an exclusion it does not know,
+ * the same way it would refuse an unknown `kind`. The enum grows only for something an installation
+ * genuinely leaves behind, never as a place to note a nicety (ADR-0006, #433). Growing it costs the
+ * direction nobody migrates in — a bundle written HERE is refused by an installation older than
+ * this line, while every bundle written before it still parses, which is the direction 0.22.0's
+ * rebuild actually runs.
+ */
+export const BundleExclusion = z.enum([
+    "version-history",
+    "grants",
+    "flow-runs",
+    "archived-nodes",
+    "unpublished-flow-changes",
+]);
+export const BundleManifest = z.strictObject({
+    version: z.literal(1),
+    exportedAt: IsoDateTime,
+    // The node the export started at; `null` is the root of the tree — the whole installation as the
+    // exporting caller may read it.
+    rootId: IntelId.nullable(),
+    entries: z.array(BundleManifestEntry),
+    excluded: z.array(BundleExclusion),
+});
+// ── Bundle import (#137) ────────────────────────────────────────────────────────────────────────
+/**
+ * What one import made. Import always creates new nodes — no merge, no overwrite, no restored IDs
+ * (#137, phase 1) — so the answer is counts and the new roots, never a diff. `replayed` marks the
+ * idempotent second answer to the same key: nothing was created twice.
+ *
+ * ⚠️ `excluded` is what the IMPORT knows about itself, never what the bundle claimed (ADR-0006,
+ * #433). A subtree moved between installations arrives with one version per node, no grants and no
+ * runs, and until now nothing said so at the moment somebody could still act on it — the word stood
+ * only in a `manifest.json` inside the zip that had already been written.
+ *
+ * It is deliberately NOT read back out of that manifest. A hand-written bundle saying `excluded: []`
+ * would then make the import report that nothing was left behind, and the import would launder
+ * somebody else's claim into an answer that sounds like its own — the trap `absence` is bound
+ * against in `BundleManifestEntry` above (#534, #560). The five exclusions hold for every import
+ * this build performs, with a manifest or from a naked folder, so this is a constant of the code.
+ */
+export const BundleImportResult = z.strictObject({
+    nodes: z.number().int().nonnegative(),
+    flows: z.number().int().nonnegative(),
+    rootNodeIds: z.array(IntelId),
+    replayed: z.boolean(),
+    excluded: z.array(BundleExclusion),
+});

package/dist/contract/contract.d.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+export declare const IntelId: z.ZodString;
+export declare const IsoDateTime: z.ZodISODateTime;
+export declare const IdempotencyKey: z.ZodString;
+/**
+ * The short name a document or a published flow is offered under as a slash command (#775).
+ *
+ * ⚠️ One described primitive rather than the same sentence in two files, for the reason
+ * `IdempotencyKey` above gives: a document and a flow take the same kind of name out of the same
+ * catalogue, and a copy would be a second place for one sentence to drift. It sits here rather than
+ * in `node.ts` because `flow.ts` states it too, and this is the file both may read.
+ *
+ * ⚠️ The refusal spells the GRAMMAR, not the verdict. Zod's own `Invalid` tells a caller who sent
+ * `CRM Outreach` that something was wrong and not what would have worked, and the one thing they
+ * need is that the answer is `crm-outreach`.
+ *
+ * ⚠️ Uniqueness is NOT in this schema and cannot be: it is a question about the whole installation,
+ * across documents and flows at once, and it is answered where the write happens. A name another
+ * node or flow already holds is refused by name there, never quietly turned into a second one.
+ */
+export declare const PromptName: z.ZodString;
+/**
+ * The version a write is made against, in the one form every writer of versioned content takes it.
+ *
+ * ⚠️ It lived beside the two node writers until #459 and moved here when the flow graph became the
+ * third — the point at which the repository stops copying and names the thing. It could not simply
+ * be imported: `flow.ts` may not depend on `node.ts` (the graph is `table → node`, `flow-run →
+ * flow`, and everything → here), and a copy would have been a second place for one sentence to
+ * drift, which is exactly what `IdempotencyKey` above exists to avoid.
+ *
+ * ⚠️ Nullable and required are not the same thing, and here they stand together (#437). `null` is
+ * how something that has no version yet is addressed, and it is the only way to write its first
+ * content; leaving the field out says nothing at all and is refused. Whoever leaves it out is
+ * almost always holding a node or a flow created one call earlier, and the plain type error they
+ * used to get — "expected string, received undefined" — reads as "this field must be an id", about
+ * a field that cannot have one yet. Both refusals therefore name both ways instead.
+ *
+ * ⚠️ It stays required once a version exists, and that is what it is for: a mismatch is answered
+ * with a `409` rather than by overwriting somebody else's newer version. Making it `optional()` to
+ * smooth the first write is the repair that breaks the guard — an absent field would then have to
+ * mean "there is none", and the forgetful caller silently replaces the newest one.
+ *
+ * ⚠️ The bounds remain `IntelId`'s. The repeated `min(1)` adds no rule — it only puts the sentence
+ * on the second value that gets tried after `undefined`, the empty string.
+ *
+ * ⚠️ The sentence says what the field TAKES, not what the caller did wrong. It answers a wrong type
+ * as well as an absent field, and "is required" would be false about the first — which would be
+ * this same ticket one corner further on. A value that is merely too long keeps Zod's own `Too
+ * big`: that one is already a true statement about what was sent.
+ *
+ * ⚠️ The JSON Schema it produces is the one `IntelId.nullable()` produced — an `anyOf` of the
+ * bounded string and `null`, still `required` — so nothing on the MCP surface moves when a field
+ * changes over to it.
+ */
+export declare function baseVersion(rule: string): z.ZodUnion<readonly [z.ZodString, z.ZodNull]>;
+export declare const UI_LANGUAGES: readonly ["en", "de", "es"];
+export type UiLanguage = (typeof UI_LANGUAGES)[number];
+/**
+ * A set of things the reader is only partly entitled to see: the ones they may see BY NAME, the
+ * rest as a NUMBER (ADR-0004 §3). Never the titles of the rest, in any field, ever — a warning or a
+ * refusal must not become a way of reading the tree.
+ *
+ * ⚠️ It lives here rather than in `share.ts` because two domains state it: a grant says what it
+ * does not reach (`UnreadableNodes`), and a refusal says who is still calling in
+ * (`ProblemDetails.callers`, #448). `contract.ts` may not import from `share.ts` — the graph
+ * between these files has to stay acyclic — and a copy would be a second place for one rule to
+ * drift, which is what `IdempotencyKey` and `baseVersion` above exist against.
+ */
+export declare const NamedOrCounted: z.ZodObject<{
+    titles: z.ZodArray<z.ZodString>;
+    hidden: z.ZodNumber;
+}, z.core.$strict>;
+export type NamedOrCounted = z.infer<typeof NamedOrCounted>;
+/**
+ * ⚠️ `callers` is the one member here that is not about every problem, and it is deliberate (#448).
+ * RFC 9457 allows extension members for exactly this: `folder_execute_in_use` refuses to narrow a
+ * library folder while flows from outside still call into it, and the CALLERS are the only thing
+ * that makes the refusal actionable. They used to exist only inside `detail` — an English sentence
+ * built on the server — so a German or Spanish surface could do nothing but print it verbatim, and
+ * no surface could shorten it or link the titles.
+ *
+ * The split is the point: the server decides WHAT is named and what is only counted, because that
+ * is an authorization answer nobody else can give; the surface decides how the sentence READS,
+ * because that is a language answer no server can give.
+ *
+ * `detail` keeps its sentence rather than emptying out — MCP hands a model prose and has nothing to
+ * formulate with, and an empty `detail` beside a new field would be the worst of the three states.
+ * It is absent on every other problem, so a reader must not treat its presence as guaranteed.
+ */
+export declare const ProblemDetails: z.ZodObject<{
+    type: z.ZodString;
+    status: z.ZodNumber;
+    title: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    instance: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+    callers: z.ZodOptional<z.ZodObject<{
+        titles: z.ZodArray<z.ZodString>;
+        hidden: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ProblemDetails = z.infer<typeof ProblemDetails>;
+export declare const SessionUser: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodEmail;
+    name: z.ZodNullable<z.ZodString>;
+    isAdmin: z.ZodBoolean;
+}, z.core.$strict>;
+export type SessionUser = z.infer<typeof SessionUser>;
+export declare const LinkConfiguration: z.ZodObject<{
+    resourceId: z.ZodString;
+}, z.core.$strict>;