@anchrd/intel-contract 0.13.0 → 0.15.0

package/README.md

@@ -26,6 +26,86 @@ Mutation inputs are strict: an unknown field is rejected rather than silently dr
 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.
 
+Each domain has its own subpath — `/node`, `/table`, `/share`, `/tool`, `/flow`, `/flow-run`,
+`/bundle` — and the root export carries only the shared primitives. Import from the narrowest
+subpath that has the symbol.
+
+## 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
+import { BlockNoteDocument, BlockNoteMediaType } from "@anchrd/intel-contract/node";
+
+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 carries no grants of its own
+
+`node_grant_create` addresses nodes. A flow has no grants; it inherits those of the folder it lives
+in. To change who reaches a flow, share its folder — or move the flow.
+
+### 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

package/dist/contract/bundle.d.ts

@@ -0,0 +1,85 @@
+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";
+    table: "table";
+    attachment: "attachment";
+    agent: "agent";
+    board: "board";
+    flow: "flow";
+}>;
+export type BundleEntryKind = z.infer<typeof BundleEntryKind>;
+export declare const BundleManifestEntry: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        folder: "folder";
+        document: "document";
+        table: "table";
+        attachment: "attachment";
+        agent: "agent";
+        board: "board";
+        flow: "flow";
+    }>;
+    title: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    mediaType: z.ZodNullable<z.ZodString>;
+    path: z.ZodString;
+}, z.core.$strict>;
+export type BundleManifestEntry = z.infer<typeof BundleManifestEntry>;
+export declare const BundleExclusion: z.ZodEnum<{
+    "version-history": "version-history";
+    grants: "grants";
+    "flow-runs": "flow-runs";
+    "archived-nodes": "archived-nodes";
+}>;
+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";
+            table: "table";
+            attachment: "attachment";
+            agent: "agent";
+            board: "board";
+            flow: "flow";
+        }>;
+        title: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        mediaType: z.ZodNullable<z.ZodString>;
+        path: z.ZodString;
+    }, z.core.$strict>>;
+    excluded: z.ZodArray<z.ZodEnum<{
+        "version-history": "version-history";
+        grants: "grants";
+        "flow-runs": "flow-runs";
+        "archived-nodes": "archived-nodes";
+    }>>;
+}, z.core.$strict>;
+export type BundleManifest = z.infer<typeof BundleManifest>;
+export declare const BundleImportResult: z.ZodObject<{
+    nodes: z.ZodNumber;
+    flows: z.ZodNumber;
+    rootNodeIds: z.ZodArray<z.ZodString>;
+    replayed: z.ZodBoolean;
+}, z.core.$strict>;
+export type BundleImportResult = z.infer<typeof BundleImportResult>;

package/dist/contract/bundle.js

@@ -0,0 +1,63 @@
+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",
+]);
+// 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.
+    path: z.string().min(1).max(4_000),
+});
+// 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).
+export const BundleExclusion = z.enum(["version-history", "grants", "flow-runs", "archived-nodes"]);
+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.
+export const BundleImportResult = z.strictObject({
+    nodes: z.number().int().nonnegative(),
+    flows: z.number().int().nonnegative(),
+    rootNodeIds: z.array(IntelId),
+    replayed: z.boolean(),
+});