@anchrd/intel-contract 0.20.0 → 0.22.0

package/dist/contract/bundle.d.ts

@@ -24,6 +24,19 @@ export declare const BundleEntryKind: z.ZodEnum<{
     flow: "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 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<{
@@ -39,13 +52,35 @@ export declare const BundleManifestEntry: z.ZodObject<{
     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<{
@@ -67,19 +102,46 @@ export declare const BundleManifest: z.ZodObject<{
         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

@@ -27,21 +27,83 @@ export const BundleEntryKind = z.enum([
     "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({
+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.
+    // 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).
-export const BundleExclusion = z.enum(["version-history", "grants", "flow-runs", "archived-nodes"]);
+/**
+ * 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,
@@ -52,12 +114,26 @@ export const BundleManifest = z.strictObject({
     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.
+/**
+ * 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

@@ -2,8 +2,74 @@ import { z } from "zod";
 export declare const IntelId: z.ZodString;
 export declare const IsoDateTime: z.ZodISODateTime;
 export declare const IdempotencyKey: 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;
@@ -11,6 +77,10 @@ export declare const ProblemDetails: z.ZodObject<{
     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<{

package/dist/contract/contract.js

@@ -13,6 +13,42 @@ export const IdempotencyKey = z
     .min(8)
     .max(200)
     .describe("A caller-chosen key that makes this call safe to retry: repeating the same key returns the first result instead of doing the work twice. Reuse the SAME key when retrying one attempt, and a new one for a genuinely new call.");
+/**
+ * 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 function baseVersion(rule) {
+    return z.union([IntelId.min(1, { error: rule }), z.null()], { error: rule });
+}
 // The languages whose UI catalog ships inside intel-ui. They live here rather than only in the UI
 // because `intel build` has to know them: a built-in language may be chosen as `ui.defaultLanguage`
 // without the customer listing a copy under `ui.languages` that would rot at every UI update.
@@ -21,6 +57,37 @@ export const IdempotencyKey = z
 // `i18n.unit.ts` compares it against the catalogs actually built in; a language listed here without
 // a file gives a red run there instead of a UI that starts on a catalog which does not exist.
 export const UI_LANGUAGES = ["en", "de", "es"];
+/**
+ * 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 const NamedOrCounted = z.strictObject({
+    titles: z.array(z.string().min(1).max(240)),
+    hidden: z.number().int().nonnegative(),
+});
+/**
+ * ⚠️ `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 const ProblemDetails = z.strictObject({
     type: z.string(),
     status: z.number().int().min(400).max(599),
@@ -28,6 +95,7 @@ export const ProblemDetails = z.strictObject({
     detail: z.string().optional(),
     instance: z.string().optional(),
     code: z.string().optional(),
+    callers: NamedOrCounted.optional(),
 });
 // Who the caller is, as Gate resolved it from the bearer: no token, and no capability list.
 //

package/dist/contract/flow.d.ts

@@ -672,6 +672,7 @@ export declare const FlowRequirements: z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
     }, z.core.$strict>>;
+    invalidNodes: z.ZodArray<z.ZodString>;
     hiddenNodes: z.ZodNumber;
     servers: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
@@ -730,7 +731,7 @@ export declare const GetFlowInput: z.ZodObject<{
 export type GetFlowInput = z.infer<typeof GetFlowInput>;
 export declare const SaveFlowVersionInput: z.ZodObject<{
     flowId: z.ZodString;
-    baseVersionId: z.ZodNullable<z.ZodString>;
+    baseVersionId: z.ZodUnion<readonly [z.ZodString, z.ZodNull]>;
     graph: z.ZodObject<{
         nodes: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"trigger">;

package/dist/contract/flow.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { IdempotencyKey, IntelId, IsoDateTime, LinkConfiguration } from "./contract.js";
+import { baseVersion, IdempotencyKey, IntelId, IsoDateTime, LinkConfiguration, } from "./contract.js";
 import { serverOf, ToolName, ToolServerHandle } from "./tool.js";
 export const FlowNodeId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/);
 export const FlowPosition = z.strictObject({ x: z.number().finite(), y: z.number().finite() });
@@ -259,11 +259,24 @@ export const ReferencedNode = z.strictObject({
 // (ADR-0004 §4). For tools it can only ever be the latter, because the catalog is a live query with
 // the requesting user's own token (ADR-0003).
 //
-// ⚠️ `nodes` names only what the asking user may see. The rest is `hiddenNodes`, a count.
+// ⚠️ `nodes` names only what the asking user may see. The rest falls into TWO fields, and keeping
+// them apart is the whole of #509: `invalidNodes` are references that name nothing at all any more,
+// `hiddenNodes` is a count of the ones that exist and are out of this reader's reach.
+//
+// ⚠️ They used to be one number, and the number was read out as "you cannot see it" — a sentence
+// about a PERMISSION, in front of a broken link. The two states suggest opposite actions and only
+// one of them helps: with a permission one asks for access and waits, with a dead reference the step
+// has to be replaced before the flow can run at all. #492 decided that such a reference is marked
+// visibly invalid rather than left silently pointed at an id nothing answers.
+//
+// ⚠️ `invalidNodes` carries IDS, never titles, and that is not the same concession `hiddenNodes`
+// makes. There is nothing left to name — the row is gone — and the id is one the caller sent us out
+// of a graph they may already read, so it discloses nothing they did not write themselves.
 export const FlowRequirements = z.strictObject({
     flowId: IntelId,
     versionId: IntelId.nullable(),
     nodes: z.array(ReferencedNode),
+    invalidNodes: z.array(IntelId),
     hiddenNodes: z.number().int().nonnegative(),
     servers: z.array(ToolServerHandle),
 });
@@ -375,7 +388,12 @@ export const GetFlowInput = z.strictObject({
 });
 export const SaveFlowVersionInput = z.strictObject({
     flowId: IntelId.describe("Flow to append a version to."),
-    baseVersionId: IntelId.nullable().describe("The version this edit was made against, from flow_get, or `null` for a flow that has none yet. If the flow has moved on since, the call is refused rather than overwriting the newer version."),
+    // ⚠️ `baseVersion`, not `IntelId.nullable()` (#459). The field is required-nullable either way;
+    // what changes is what a caller who left it out is told. Zod's own `expected string, received
+    // undefined` reads as "this needs an id" to somebody holding a flow created one call earlier —
+    // whose `currentVersionId` is `null` and can be nothing else. That reading cost a session at
+    // #437, and this was the third field carrying it.
+    baseVersionId: baseVersion("baseVersionId takes the `currentVersionId` from flow_get, or null when the flow has no version yet — and it has to be sent.").describe("The version this edit was made against, from flow_get, or `null` for a flow that has none yet. If the flow has moved on since, the call is refused rather than overwriting the newer version."),
     graph: FlowGraph.describe("The complete graph — nodes and edges — not a patch. It is validated before it is stored, so an unreachable node or a dangling edge is refused here rather than at run time."),
     idempotencyKey: IdempotencyKey,
 });

package/dist/contract/node.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { IdempotencyKey, IntelId, IsoDateTime } from "./contract.js";
+import { baseVersion, IdempotencyKey, IntelId, IsoDateTime } from "./contract.js";
 // What this installation is equipped to do — deployment facts, never the caller's permissions
 // (those stay behind each door, where `/session` deliberately does not carry them). `agentRuntime`
 // says whether an agent Worker is bound at all (#190): without it the UI offers no "New agent" and
@@ -95,30 +95,6 @@ export const CreateNodeInput = z.strictObject({
         .describe("Optional sentence about the node, for readers rather than for search ranking."),
     idempotencyKey: IdempotencyKey,
 });
-/**
- * The version a write is made against, in the one form both writers of node content take it.
- *
- * ⚠️ Nullable and required are not the same thing, and here they stand together (#437). `null` is
- * how a node 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 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.
- *
- * ⚠️ 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.
- */
-function baseVersion(rule) {
-    return z.union([IntelId.min(1, { error: rule }), z.null()], { error: rule });
-}
 export const SaveNodeVersionInput = z.strictObject({
     nodeId: IntelId.describe("Document node to append a version to."),
     baseVersionId: baseVersion("baseVersionId takes the `currentVersionId` from node_get, or null when the node has no version yet — and it has to be sent.").describe("The version this edit was made against — `currentVersionId` from node_get. If the node has moved on since, the call is refused rather than overwriting the newer version; pass `null` only for a node that has no version yet."),
@@ -194,7 +170,13 @@ export const PurgeNodeInput = z.strictObject({
     nodeId: IntelId.describe("Node to delete for good. It must already be archived — a living node has no path into nothing."),
     idempotencyKey: IdempotencyKey,
 });
-export const PurgeNodePreviewInput = z.strictObject({ nodeId: IntelId });
+// The question `PurgeNodeInput` cannot be asked afterwards: what goes with it, while it is all
+// still there to be counted. Described since #586, because the count reached MCP that day — and a
+// surface that may delete without being able to look first is the state `destructive.md` calls a
+// confirmation that cannot name what disappears.
+export const PurgeNodePreviewInput = z.strictObject({
+    nodeId: IntelId.describe("Archived node a purge would delete. Answers how many items would go with it and how many documents link to it from outside, and changes nothing. A node that is not archived is refused here for the same reason node_purge refuses it."),
+});
 export const PurgeNodePreview = z.strictObject({
     inboundLinks: z.number().int().nonnegative(),
     totalItems: z.number().int().positive(),

package/dist/contract/share.d.ts

@@ -24,6 +24,14 @@ export declare const ListFlowGrantsInput: z.ZodObject<{
     flowId: z.ZodString;
 }, z.core.$strict>;
 export type ListFlowGrantsInput = z.infer<typeof ListFlowGrantsInput>;
+export declare const ListEffectiveAccessInput: z.ZodObject<{
+    resourceId: z.ZodString;
+}, z.core.$strict>;
+export type ListEffectiveAccessInput = z.infer<typeof ListEffectiveAccessInput>;
+export declare const ListFlowEffectiveAccessInput: z.ZodObject<{
+    flowId: z.ZodString;
+}, z.core.$strict>;
+export type ListFlowEffectiveAccessInput = z.infer<typeof ListFlowEffectiveAccessInput>;
 export declare const ResourceGrant: z.ZodObject<{
     id: z.ZodString;
     resourceId: z.ZodString;

package/dist/contract/share.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { IdempotencyKey, IntelId, IsoDateTime } from "./contract.js";
+import { IdempotencyKey, IntelId, IsoDateTime, NamedOrCounted } from "./contract.js";
 // ⚠️ There is no `ContextPolicy`, and it is not coming back in this shape (#76). It said whether a
 // document should be pinned into a context, be found by relevance, or be named explicitly — an
 // instruction to a retrieval Intel does not perform. Intel hands out references and the agent
@@ -23,6 +23,21 @@ export const ListGrantsInput = z.strictObject({
 export const ListFlowGrantsInput = z.strictObject({
     flowId: IntelId.describe("Flow whose direct grants to list. Access inherited from the folder it is filed in is not a grant on this flow and is not listed here."),
 });
+// ⚠️ A DIFFERENT question from the two above, not a fuller answer to them (#586). The `*GrantsInput`
+// pair asks what sits ON this one resource; these two ask who REACHES it once inheritance is
+// resolved — every grant along the folders above plus the owners, who need no grant row at all. On
+// the everyday resource, whose access comes from the folder it is filed in, the first answer is
+// empty and this one is not, so a caller that reaches for the wrong one is told "nobody" about
+// something half the organization can open.
+//
+// Two inputs rather than one widened `resourceId`, for the reason the pair above gives: the id
+// names a different table, and the queries behind them are two statements over two sets of tables.
+export const ListEffectiveAccessInput = z.strictObject({
+    resourceId: IntelId.describe("Node to answer for. The answer crosses the folders above it and names owners as well as grants, so it is not the list node_grant_list gives."),
+});
+export const ListFlowEffectiveAccessInput = z.strictObject({
+    flowId: IntelId.describe("Flow to answer for. The answer includes what the folder it is filed in passes down and names owners as well as grants, so it is not the list flow_grant_list gives."),
+});
 export const ResourceGrant = z.strictObject({
     id: IntelId,
     resourceId: IntelId,
@@ -32,13 +47,20 @@ export const ResourceGrant = z.strictObject({
     createdBy: IntelId,
     createdAt: IsoDateTime,
 });
+// The word means exactly the same thing on a node grant and on a flow grant, so it is described
+// once — the rule this package states about `IdempotencyKey`, applied within one file rather than
+// across the package. Two copies are two places to drift, and both of them ship in `tools/list`.
+//
+// ⚠️ What is refused is decided by `deps.now()` in the application layer and cannot be expressed
+// here (#442); this sentence names the answer a caller gets, it does not produce it.
+const GrantExpiresAt = IsoDateTime.nullable()
+    .default(null)
+    .describe("When the grant stops working, or `null` for one that does not expire on its own. A time that is not in the future is refused with `grant_already_expired`: a grant that could never work is not created.");
 export const ShareInput = z.strictObject({
     resourceId: IntelId.describe("Node to grant access to. A grant on a folder is inherited by everything beneath it, which is the usual way to share a whole area."),
     principal: SharePrincipal.describe("Who gets the access: a Gate user by id, someone by verified email address, or the whole organization."),
     verb: ResourceVerb.describe("What they may do. Each verb is granted on its own and none implies another: `read` reads, `write` writes, `execute` runs a flow, `share` passes access on. Seeing a process is deliberately separable from being allowed to start it."),
-    expiresAt: IsoDateTime.nullable()
-        .default(null)
-        .describe("When the grant stops working, or `null` for one that does not expire on its own."),
+    expiresAt: GrantExpiresAt,
     idempotencyKey: IdempotencyKey,
 });
 export const RevokeGrantInput = z.strictObject({
@@ -50,9 +72,7 @@ export const ShareFlowInput = z.strictObject({
     flowId: IntelId.describe("Flow to grant access to. A grant here reaches this flow and nothing else — not the folder it is filed in, and not the flows it calls."),
     principal: SharePrincipal.describe("Who gets the access: a Gate user by id, someone by verified email address, or the whole organization."),
     verb: ResourceVerb.describe("What they may do. Each verb is granted on its own and none implies another: `read` opens the flow, `write` edits it, `execute` runs it, `share` passes access on."),
-    expiresAt: IsoDateTime.nullable()
-        .default(null)
-        .describe("When the grant stops working, or `null` for one that does not expire on its own."),
+    expiresAt: GrantExpiresAt,
     idempotencyKey: IdempotencyKey,
 });
 export const RevokeFlowGrantInput = z.strictObject({
@@ -66,10 +86,11 @@ export const RevokeFlowGrantInput = z.strictObject({
 //
 // ⚠️ `titles` holds only the documents the sharer may see; everything else is in `hidden` as a
 // number. A warning must not become a way of reading titles out of the tree.
-export const UnreadableNodes = z.strictObject({
-    titles: z.array(z.string().min(1).max(240)),
-    hidden: z.number().int().nonnegative(),
-});
+//
+// It IS `NamedOrCounted` — one schema, under the name this domain calls it by. The shape moved to
+// `contract.ts` when a refusal started carrying it too (#448); it is not restated here, because two
+// declarations of one rule are two places for it to drift.
+export const UnreadableNodes = NamedOrCounted;
 // The grant is in the answer, so the warning cannot be mistaken for a refusal: it is written first
 // and described afterwards. Blocking would force everyone who uses a central policy document to
 // duplicate it, which is the opposite of what one tree is for (ADR-0004 §4).

package/package.json

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