@anchrd/intel 0.59.0

package/src/contract/README.md

@@ -0,0 +1,102 @@
+# The Intel wire contract
+
+The Zod schemas that describe every payload crossing Intel's HTTP, MCP and browser surfaces. They
+travel inside [`@anchrd/intel`](https://www.npmjs.com/package/@anchrd/intel) at `src/contract`, both
+as source and as built JavaScript under `dist/contract`.
+
+⚠️ **They carry no `exports` subpath of their own.** They used to be the separate package
+`@anchrd/intel-contract`, which is being retired in favour of this package; nothing outside
+`@anchrd/intel` read
+it, so nothing re-exports it now. If you write your own client, the file to read is the one for your
+domain — `node.ts`, `table.ts`, `share.ts`, `tool.ts`, `flow.ts`, `flow-run.ts`, `bundle.ts`,
+`audit.ts`, `board.ts`, `feed.ts` — with `contract.ts` holding only the shared primitives.
+
+Mutation inputs are strict: an unknown field is rejected rather than silently dropped, so a typo in
+a client never becomes a value that quietly fails to apply. Types are inferred from the schemas, so
+`z.infer` gives you the same shape the server validates against.
+
+## Six things that cost a first-time caller an afternoon
+
+Every one of these was found by somebody writing against the real API and guessing.
+
+### A refusal hides in one of two fields, never both
+
+Intel answers failures as RFC 9457 problem details, and **which field carries the sentence depends
+on who refused**:
+
+| Kind of refusal | `title` | `detail` |
+|---|---|---|
+| Intel itself — a permission, a conflict, an invalid flow graph | the actual reason | absent |
+| Schema validation — a bad or missing field | `Request validation failed` | the actual reason, field by field |
+
+A client that logs only `detail` sees nothing for the first kind; one that logs only `title` sees
+`Request validation failed` and nothing about which field. **Read both.** `code` is the stable
+machine-readable half and is always present.
+
+### `baseVersionId` takes `null`, and it is still required
+
+Fields declared `nullable()` and not `optional()` are **required**: `null` is a value they take, and
+leaving them out is refused. That is deliberate everywhere a write names the version it was made
+against — `SaveNodeVersionInput`, `SaveAttachmentInput`, `SaveFlowVersionInput`. `null` is the only
+way to write the first content of a node that has none, and the field stays required so a caller who
+simply forgot it is refused instead of overwriting whatever somebody else wrote in between.
+
+Neither `undefined` nor `""` works. Send the `currentVersionId` from `node_get`, or `null`.
+
+### `mediaType` decides whether the browser can open what you wrote
+
+`SaveNodeVersionInput.mediaType` defaults to `text/markdown`, and for plain text that is right. It is
+**wrong for anything the node editor should be able to open**: the editor stores and reads
+`BlockNoteMediaType` (`application/vnd.anchrd.intel.blocknote+json`) with a `BlockNoteDocument` body.
+
+Content in any other shape is stored intact, indexed and searchable — and the editor opens **empty**
+on it, because it cannot parse it. Nothing reports an error, and a save from that empty editor
+replaces what was written. If a person is meant to edit the document afterwards, write it as a
+`BlockNoteDocument`:
+
+```ts
+// from node.ts: BlockNoteDocument, BlockNoteMediaType
+
+const content = JSON.stringify(
+  BlockNoteDocument.parse({ format: "blocknote", schemaVersion: 1, blocks, markdown }),
+);
+// … then save with mediaType: BlockNoteMediaType
+```
+
+### In a flow graph, a tool is a link, not a step
+
+Flow nodes sit in three layers. `trigger` and `output` are markers, `instruction`, `condition` and
+`subflow` are steps — and `folder`, `document`, `upload`, `table` and `tool` are **links**.
+
+A link never stands in the chain of work. It hangs off an `instruction` or a `condition` — not off a
+marker and not off a `subflow` — and the edge that attaches it must carry `kind: "context"`:
+
+```jsonc
+{ "source": "<instruction id>", "target": "<tool id>", "kind": "context" }
+```
+
+⚠️ `FlowEdge.kind` **defaults to `"flow"`**, so an edge written without it becomes an order-of-work
+edge and the tool ends up in the chain. The graph is then refused with
+`Node <id> is a link and must be attached to a step` — in `title`, per the first item above. A step
+may hold several links; one link belongs to exactly one step.
+
+### A flow is not a node, and has its own grant calls
+
+`node_grant_create` addresses nodes; `flow_grant_create` addresses flows. A flow is reached by both:
+the folder it is filed in passes its grants down, and a grant may sit on the flow itself. The two
+add up — the flow grant never replaces what the folder passes down.
+
+⚠️ A grant on one flow reaches **that flow** and nothing else — not the folder, and not the flows it
+calls. `ShareResult` says so: `unrunnable` names the sub-flows the new principal could not start,
+by title where you may see them and by count where you may not.
+
+### Import takes its idempotency key as a header
+
+Every mutation in this contract carries an `idempotencyKey` field. Bundle import is the one
+exception, because its **body is the zip**: the key travels as the `idempotency-key` HTTP header
+instead, and a request without it is refused.
+
+## License
+
+Proprietary. Published publicly for installation convenience; this is not an open-source license and
+grants no right to use, copy, modify or redistribute the software. Contact Anchrd for licensing.

package/src/contract/audit.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { IntelId, IsoDateTime } from "./contract.ts";
+
+// Which kind of resource an event is about — all three the column carries, since #774.
+//
+// ⚠️ It was `["node"]` alone until then, and that was a decision rather than a gap (#620): each
+// kind needs a DIFFERENT visibility check, and asking for one that had none was REFUSED rather than
+// answered with an empty list. An empty list reads as "nothing happened", and a consumer built on
+// that would miss every flow event without ever learning they exist.
+//
+// What changed is that the other two checks now exist. `flow` walks the folder a flow hangs in
+// (`flowInSubtree`), and `flow-run` walks one join further — run → flow → folder — which #767 built
+// for the feed. **Widening the enum without those walks would have been the silent answer the
+// original decision refused**, so the order matters: the check first, the enum second.
+export const AuditResourceType = z.enum(["node", "flow", "flow-run"]);
+export type AuditResourceType = z.infer<typeof AuditResourceType>;
+
+// One line of the change journal. `resourceId` is the node the event is about; `actorId` is who
+// caused it. `metadata` is whatever the write site recorded — its shape belongs to `action` and is
+// deliberately not typed here, because a schema per action would have to be kept in step with 11
+// write sites and would go stale in silence.
+export const AuditEvent = z.strictObject({
+  id: IntelId,
+  actorId: z.string().min(1),
+  action: z.string().min(1),
+  resourceType: AuditResourceType,
+  resourceId: IntelId,
+  metadata: z.record(z.string(), z.unknown()),
+  occurredAt: IsoDateTime,
+});
+export type AuditEvent = z.infer<typeof AuditEvent>;
+
+// ⚠️ Opaque BY CONTRACT, not merely by encoding. The reader gets a string back and hands the same
+// string in again; it must not take it apart, and it must not build one.
+//
+// The reason is that the cursor is a PAIR — `(occurredAt, id)` — and the pair is the whole point.
+// A timestamp alone cannot separate two events written in the same millisecond, which for a batch
+// is the normal case rather than the exception; a reader continuing on `occurredAt > X` skips the
+// second one silently. If the cursor were two fields, a caller would eventually send only the
+// timestamp, and the loss would look like nothing at all: no error, no log, just an event that
+// never arrived.
+export const AuditCursor = z.string().min(1).max(400);
+
+export const AuditListRequest = z.strictObject({
+  resourceType: AuditResourceType.describe(
+    "Which kind of resource to read events about: `node` for documents, folders, tables and attachments, `flow` for changes to a flow itself, `flow-run` for its runs. One kind per call — the three are separate journals with separate cursors.",
+  ),
+  after: AuditCursor.optional().describe(
+    "Where to continue: the `nextCursor` of a previous answer, passed back unchanged. Omit it to start at the oldest event you may see. Do not build one — it is opaque on purpose.",
+  ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(200)
+    .default(50)
+    .describe("How many events to return at most. The answer may be shorter."),
+});
+export type AuditListRequest = z.infer<typeof AuditListRequest>;
+
+// `nextCursor` is the cursor of the LAST returned row — a position, not a page number. A reader
+// stores it and sends it back as `after`.
+//
+// ⚠️ **It answers WHERE THE READER GOT TO, never whether more is waiting.** Those are two questions,
+// and for a while one field answered both: the cursor was omitted whenever no further page followed,
+// so a reader that was catching up got fifty events and no position, started over on its next run,
+// and would have delivered the same fifty for ever. Measured against the running installation
+// (`#793`); a reader paging through never notices, because it always asks for a full page.
+//
+// ⚠️ **`hasMore` is the other question, and it is a MAY, not a promise.** The journal is a live table
+// and the rows a reader may see can shrink between calls. Treating `hasMore` as "there is data" is a
+// fair reading; treating an empty answer as "the feed ended" is not.
+export const AuditListResponse = z.strictObject({
+  events: z.array(AuditEvent),
+  // `null` only when nothing was returned: no rows, no position.
+  nextCursor: AuditCursor.nullable(),
+  /**
+   * ⚠️ **Added rather than repurposed** (`#793`). A reader written against the old shape reads
+   * "cursor present" as "more may follow"; it now sees a cursor on the last page as well and asks
+   * once more, which answers empty. That costs one request and loses nothing — whereas changing what
+   * `nextCursor` MEANS would have made those readers skip.
+   */
+  hasMore: z.boolean(),
+});
+export type AuditListResponse = z.infer<typeof AuditListResponse>;

package/src/contract/board.ts

@@ -0,0 +1,306 @@
+import { z } from "zod";
+import { IdempotencyKey, IntelId, IsoDateTime } from "./contract.ts";
+
+// 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.",
+    ),
+});
+export type BoardColumn = z.infer<typeof BoardColumn>;
+
+// 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(),
+});
+export type BoardTask = z.infer<typeof BoardTask>;
+
+// ⚠️ 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 type BoardTaskFilter = z.infer<typeof BoardTaskFilter>;
+
+export const BoardGetInput = BoardTaskFilter.extend({
+  boardId: IntelId.describe("The board node to read. Must be a node of kind `board`."),
+});
+export type BoardGetInput = z.infer<typeof BoardGetInput>;
+
+// 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 type BoardView = z.infer<typeof BoardView>;
+
+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 type BoardUpdateInput = z.infer<typeof BoardUpdateInput>;
+
+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,
+});
+export type BoardTaskCreateInput = z.infer<typeof BoardTaskCreateInput>;
+
+// ⚠️ 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,
+});
+export type BoardTaskUpdateInput = z.infer<typeof BoardTaskUpdateInput>;
+
+// ── 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 type DirectoryPerson = z.infer<typeof DirectoryPerson>;
+
+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.",
+    ),
+});
+export type BoardAssigneeSearchInput = z.infer<typeof BoardAssigneeSearchInput>;
+
+// ⚠️ 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 type DirectoryResolveInput = z.infer<typeof DirectoryResolveInput>;
+
+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),
+});
+export type DirectoryPersonList = z.infer<typeof DirectoryPersonList>;

package/src/contract/bundle.ts

@@ -0,0 +1,157 @@
+import { z } from "zod";
+import { IntelId, IsoDateTime } from "./contract.ts";
+
+// ── 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",
+]);
+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 const BundleEntryAbsence = z.enum(["no-content"]);
+export type BundleEntryAbsence = z.infer<typeof BundleEntryAbsence>;
+
+// 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"],
+    },
+  );
+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 const BundleExclusion = z.enum([
+  "version-history",
+  "grants",
+  "flow-runs",
+  "archived-nodes",
+  "unpublished-flow-changes",
+]);
+export type BundleExclusion = z.infer<typeof BundleExclusion>;
+
+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),
+});
+export type BundleManifest = z.infer<typeof BundleManifest>;
+
+// ── 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),
+});
+export type BundleImportResult = z.infer<typeof BundleImportResult>;