@ai-matrx/content-ir 0.10.4 → 0.11.0

package/dist/directives.d.cts

@@ -0,0 +1,294 @@
+import { K as KIND_KEY } from './kind-schema.types-CwncWj9U.cjs';
+
+/**
+ * Kind Directives — the grammar, the shell, and the position law (kernel edition).
+ *
+ * ONE system (Arman, 2026-08-23): the Matrx Envelope/Directive protocol and the
+ * Content IR kind system are one system. A directive is an ordinary kind
+ * instance — `{ "__kind": "directive_v1_<class>_<noun>", "items": [...] }` —
+ * whose registered shape additionally carries execution semantics on the
+ * server. This module is the PURE half, ported verbatim from the aidream source
+ * of record (`packages/matrx-graph/matrx_graph/content_ir/directives.py`) so
+ * every UI parses the grammar identically. It lives in the KERNEL because a
+ * host that can parse a kind must be able to recognise a directive without a
+ * second copy of these rules (matrx-frontend carried the only copy until
+ * 2026-09-08; Workflow Studio had none and rendered directives as raw text).
+ *
+ * THE SLUG GRAMMAR — `directive_v<version>_<class>_<noun>`:
+ *  - `directive_v` is a RESERVED prefix; a hand-authored kind may never claim it.
+ *  - `<class>` comes from a CLOSED vocabulary, so parsing is unambiguous even
+ *    though nouns contain underscores: `directive_v1_reference_create_task` is
+ *    `(reference, "create_task")`.
+ *  - capability is DERIVED from the class, never stored twice.
+ */
+
+/** The reserved slug prefix. ANY kind slug starting with this belongs to the Kind Directives protocol. */
+declare const RESERVED_PREFIX: "directive_v";
+/** Current directive grammar version. */
+declare const DIRECTIVE_VERSION: 1;
+/** The full prefix of a v1 directive slug. */
+declare const SLUG_PREFIX: "directive_v1_";
+/** The CLOSED class vocabulary. Closed is what makes the grammar parseable. */
+declare const CLASSES: readonly ["reference", "view", "create", "update", "delete", "action", "validation", "secret"];
+type DirectiveClass = (typeof CLASSES)[number];
+type DirectiveCapability = "pure" | "sensitive" | "side_effect";
+/** class → capability. DERIVED, never stored on a shape. */
+declare const CAPABILITY_BY_CLASS: Readonly<Record<DirectiveClass, DirectiveCapability>>;
+/** The classes that EXECUTE at an agent's output root — a durable side effect. */
+declare const SIDE_EFFECT_CLASSES: ReadonlySet<DirectiveClass>;
+/**
+ * The classes that resolve to a LIVE VALUE inside content. STRICT BY CHOICE,
+ * mirroring the server: exactly `reference` + `secret`.
+ */
+declare const IN_CONTENT_CLASSES: ReadonlySet<DirectiveClass>;
+/** A parsed directive slug. `slug` round-trips through `buildDirectiveSlug`. */
+interface DirectiveSlug {
+    slug: string;
+    version: number;
+    directiveClass: DirectiveClass;
+    noun: string;
+    capability: DirectiveCapability;
+    /** Executes at an agent's output root (THE position law, half one). */
+    executes: boolean;
+    /** Resolves to a live value inside content (THE position law, half two). */
+    inContent: boolean;
+}
+declare function isDirectiveClass(value: unknown): value is DirectiveClass;
+/**
+ * Whether `slug` sits in the reserved Kind Directives namespace. Deliberately
+ * broader than {@link parseDirectiveSlug}: a MALFORMED `directive_v…` slug is
+ * still reserved, so authoring gates reject it instead of letting a near-miss
+ * through as an ordinary kind.
+ */
+declare function isReservedDirectiveSlug(slug: unknown): slug is string;
+/**
+ * `("create", "task") → "directive_v1_create_task"`. THROWS on a class outside
+ * the closed vocabulary or an ill-formed noun — a slug that cannot be parsed
+ * back must never be mintable.
+ */
+declare function buildDirectiveSlug(directiveClass: string, noun: string, version?: number): string;
+/**
+ * Parse a directive slug, or `null` when `slug` is not one. A slug that IS in
+ * the reserved namespace but does not parse returns `null` too — pair with
+ * {@link isReservedDirectiveSlug} to tell "ordinary kind" from "malformed
+ * directive"; every such caller treats the malformed case as an ERROR.
+ */
+declare function parseDirectiveSlug(slug: unknown): DirectiveSlug | null;
+declare function capabilityOf(directiveClass: DirectiveClass): DirectiveCapability;
+/** THE position law, half one: only a side-effect class executes at an agent's output root. */
+declare function executesAtOutputRoot(directiveClass: string): boolean;
+/** THE position law, half two: only a pointer or a sensitive value resolves to a live value inside content. */
+declare function resolvesInContent(directiveClass: string): boolean;
+/**
+ * The `__kind` of `obj` when it is in the reserved namespace, else null. Reads
+ * the RESERVED namespace, not the parsed grammar, so a malformed directive is
+ * still recognised as a directive (and rejected downstream with a real message).
+ */
+declare function directiveSlugOf(obj: unknown): string | null;
+/** THE detector — a dict whose `__kind` is in the reserved namespace. */
+declare function isKindDirective(obj: unknown): boolean;
+/**
+ * The two-key shell, as it travels on the wire. A TYPE alias, not an interface,
+ * so a shell is structurally assignable to `Record<string, unknown>`.
+ */
+type KindDirectiveShell<Item = Record<string, unknown>> = {
+    /** The slug. Serialized FIRST — see the module doc. */
+    [KIND_KEY]: string;
+    items: Item[];
+};
+/**
+ * Build the two-key shell with `__kind` FIRST. Never hand-assemble the object
+ * literal elsewhere: JS preserves insertion order for string keys, and the
+ * first-key rule is what lets the streaming detector type a directive early.
+ */
+declare function buildKindDirective<Item>(slug: string, items: Item[]): KindDirectiveShell<Item>;
+/**
+ * Mid-stream recognition: the opening of a document whose FIRST key is a
+ * reserved directive slug, before the closing brace has arrived. Used by
+ * content splitters so a streaming envelope is typed early.
+ */
+declare function looksLikeDirectiveHead(content: string): boolean;
+
+/**
+ * Decode a Kind Directive — THE one entry point on every client.
+ *
+ * `decodeDirective()` recognises the shell (current OR, for stored content
+ * only, the retired 4-key one), reads the slug, and derives class + noun. A
+ * caller only ever sees a parsed {@link DecodedDirective}; nothing downstream
+ * inspects a raw shell again.
+ *
+ * ITEM VALIDATION IS THE SERVER'S. The registered item models live in aidream
+ * (`services/content_ir_directives/registry.py`) and validate on apply; a
+ * client-side copy of ~120 item models is exactly the drift the merge exists
+ * to kill. The client parses identity, routes, and renders. Mirror of aidream
+ * `services/content_ir_directives/decode.py`.
+ */
+
+/**
+ * A well-formed-looking directive that cannot be honoured (a malformed slug, or
+ * a retired shell that does not map onto the grammar). Never thrown for "this
+ * isn't a directive" — that is `null`.
+ */
+declare class DirectiveDecodeError extends Error {
+    constructor(message: string);
+}
+interface DecodedDirective {
+    /** The parsed slug — class, noun, capability and the position law. */
+    readonly parsed: DirectiveSlug;
+    readonly slug: string;
+    readonly directiveClass: DirectiveClass;
+    readonly noun: string;
+    readonly items: Record<string, unknown>[];
+    /** The two-key shell, normalised — what a confirm POST round-trips. */
+    readonly shell: Record<string, unknown>;
+    /** True when this arrived in the retired 4-key shell and was translated. */
+    readonly legacyShell: boolean;
+}
+/**
+ * A typed directive, or `null` when `value` is not a directive at all. Throws
+ * {@link DirectiveDecodeError} when it IS one but cannot be honoured.
+ */
+declare function decodeDirective(value: unknown): DecodedDirective | null;
+/**
+ * The forgiving read used at render seams: `decodeDirective`, but a directive
+ * that cannot be honoured comes back as `null` after the reason is handed to
+ * `onError`. A render seam must never take a whole message block down over one
+ * bad fence — but it must never swallow the reason either.
+ */
+declare function tryDecodeDirective(value: unknown, onError?: (message: string) => void): DecodedDirective | null;
+/** `decodeDirective` over a JSON string or an already-parsed value. Non-JSON text is `null`. */
+declare function tryDecodeDirectiveContent(content: unknown, onError?: (message: string) => void): DecodedDirective | null;
+
+/**
+ * THE ONE LEGACY SURFACE of the Kind Directives protocol — read-only.
+ *
+ * Stored content written before 2026-08-23 carries the retired 4-key shell
+ * (`matrx_version` / `kind` / `type` / `items`). This module translates it into
+ * the current two-key shell so `decodeDirective` sees one shape, forever. It
+ * never emits, never registers a shape, has no fallback branch, and every use
+ * is counted so the containment can be measured. Only `decode.ts` may import
+ * it (matrx-frontend's `check-legacy-shim-containment` and aidream's
+ * `test_legacy_shim_containment.py` enforce the mirror).
+ */
+declare function legacyShellUses(): number;
+declare function resetLegacyShellUses(): void;
+/** True ONLY for a genuine retired-shell directive claim (sentinel + a retired kind token). */
+declare function isLegacyShell(obj: unknown): boolean;
+
+/**
+ * THE AUTO-VIEW's naming half: every enrolled noun "instantly has a view" —
+ * the prefix rule gives it a renderer, and this gives it a NAME. A shape the
+ * client has never heard of must still read as "Create Agent · Agents", never
+ * as the raw `agent` token and never as a slug.
+ *
+ * The catalog (`platform.entity_types` → the server's directive catalog) is the
+ * authority for `label` / `family` / `title_column`; a host that mirrors it
+ * passes a {@link DirectiveNounCatalog}. Without one — or for a noun the
+ * catalog does not carry (a Kind Action like `plan_tree`) — the name degrades
+ * to a title-cased token: legible, honestly derived, never blank.
+ */
+
+interface DirectiveNounEntry {
+    /** The noun's human name — "Agent", "Plan tree". */
+    label?: string | null;
+    /** The catalog family ("Agents"). */
+    family?: string | null;
+    /** Which field of a row names it (`name`, `title`, …). */
+    titleColumn?: string | null;
+}
+/** A host-supplied lookup over the mirrored catalog. `undefined` = not carried. */
+type DirectiveNounCatalog = (noun: string) => DirectiveNounEntry | undefined;
+interface DirectiveDisplay {
+    /** The noun's human name — "Agent", "Plan tree". */
+    noun: string;
+    /** The catalog family ("Agents"), or "" when the catalog has none. */
+    family: string;
+    /** What this directive DOES, in the user's words — "Create", "Reference". */
+    action: string;
+    /** One line: "Create Agent". */
+    title: string;
+}
+/** `plan_node_patch` → `Plan node patch`. The honest last resort. */
+declare function titleCaseToken(token: string): string;
+/**
+ * How a class reads to a human. `action` is deliberately "Run": a Kind Action
+ * is a named procedure, and "Action Plan tree" reads like a noun phrase where a
+ * verb belongs. Mirrored by the server's kind-catalog label.
+ */
+declare const ACTION_BY_CLASS: Readonly<Record<DirectiveClass, string>>;
+declare function nounLabel(noun: string, catalog?: DirectiveNounCatalog): string;
+declare function nounFamily(noun: string, catalog?: DirectiveNounCatalog): string;
+declare function nounTitleColumn(noun: string, catalog?: DirectiveNounCatalog): string | null;
+/** Everything a generic card needs to name a directive it cannot render. */
+declare function directiveDisplay(directiveClass: DirectiveClass, noun: string, catalog?: DirectiveNounCatalog): DirectiveDisplay;
+
+/**
+ * Naming and summarising ONE item of a directive, for the compact card.
+ *
+ * THE RULE: a user is never asked to approve a write they cannot identify. The
+ * card must say WHAT is about to be created/updated/deleted, derived from
+ * authority rather than guesswork, in this order:
+ *   1. the noun's catalog `title_column` — the server's own answer to "what
+ *      names a row of this table";
+ *   2. the conventional identity fields, in a fixed order;
+ *   3. the honest last resort — "Item 2 of 3", never a blank chip and never a
+ *      slug pretending to be a name.
+ *
+ * Facts are scalars ONLY. Nesting goes to the panel, never into the row.
+ */
+/**
+ * What to call this item. `titleColumn` is the noun's catalog title column
+ * (consulted first); null when the catalog carries none.
+ */
+declare function itemTitle(item: Record<string, unknown>, titleColumn: string | null, index: number, total: number): string;
+/** A one-line subtitle when the item carries prose about itself. */
+declare function itemSubtitle(item: Record<string, unknown>): string | null;
+interface ItemFact {
+    key: string;
+    label: string;
+    value: string;
+}
+/**
+ * Up to `limit` scalar facts about the item — counts for collections, values
+ * for scalars. Nested objects are deliberately absent (they belong in the
+ * panel), and so is anything already carried by the title/subtitle.
+ */
+declare function itemFacts(item: Record<string, unknown>, limit?: number): ItemFact[];
+
+/**
+ * THE DIRECTIVE⇄KIND SEAM, client side.
+ *
+ * Arman, 2026-08-26: the envelope / Matrx-Actions system and the Shape (kind)
+ * system are ONE system with several methods inside it. They meet at the ITEM.
+ * A directive is a CONTAINER; its items are the payload, and when the server's
+ * item model is already a `KindModel`, that payload IS a registered kind
+ * instance — so the kind system already knows how to validate, render and copy
+ * it.
+ *
+ * The seam is SERVER-DERIVED (`ShapeSpec.item_kind`). Since 2026-09-08 the ONE
+ * kind endpoint publishes every directive shape as a KindDescriptor whose
+ * `items` EDGE names the item kind, so a client reads it from the same
+ * catalog it already holds — {@link directiveItemKindFromEdges}. A host that
+ * mirrors the directive catalog manifest instead passes its map as a
+ * {@link DirectiveItemKindLookup}. `null` is HONEST, never a gap-filler.
+ */
+/** A host-supplied lookup: slug → the kind ONE item is, or null. */
+type DirectiveItemKindLookup = (slug: string) => string | null;
+/** The `items` edge of a directive KindDescriptor, as the kind catalog serves it. */
+interface DirectiveItemsEdge {
+    field_name?: string;
+    fieldPath?: string;
+    child_kind?: string;
+    childKind?: string;
+}
+/** The item kind named by a directive descriptor's `items` edge, or null. */
+declare function directiveItemKindFromEdges(edges: readonly DirectiveItemsEdge[] | null | undefined): string | null;
+/**
+ * The item, presented the way the kind pipeline expects it: `__kind` FIRST so a
+ * consumer types the object from its own first key. `__kind` is ADDED, never
+ * overwritten: an item that already carries its marker keeps the value it was
+ * emitted with. Null when no kind is known — the caller owns the generic floor.
+ */
+declare function asKindInstance(item: Record<string, unknown>, kind: string | null): Record<string, unknown> | null;
+
+export { ACTION_BY_CLASS, CAPABILITY_BY_CLASS, CLASSES, DIRECTIVE_VERSION, type DecodedDirective, type DirectiveCapability, type DirectiveClass, DirectiveDecodeError, type DirectiveDisplay, type DirectiveItemKindLookup, type DirectiveItemsEdge, type DirectiveNounCatalog, type DirectiveNounEntry, type DirectiveSlug, IN_CONTENT_CLASSES, type ItemFact, KIND_KEY, type KindDirectiveShell, RESERVED_PREFIX, SIDE_EFFECT_CLASSES, SLUG_PREFIX, asKindInstance, buildDirectiveSlug, buildKindDirective, capabilityOf, decodeDirective, directiveDisplay, directiveItemKindFromEdges, directiveSlugOf, executesAtOutputRoot, isDirectiveClass, isKindDirective, isLegacyShell, isReservedDirectiveSlug, itemFacts, itemSubtitle, itemTitle, legacyShellUses, looksLikeDirectiveHead, nounFamily, nounLabel, nounTitleColumn, parseDirectiveSlug, resetLegacyShellUses, resolvesInContent, titleCaseToken, tryDecodeDirective, tryDecodeDirectiveContent };

package/dist/directives.d.ts

@@ -0,0 +1,294 @@
+import { K as KIND_KEY } from './kind-schema.types-CwncWj9U.js';
+
+/**
+ * Kind Directives — the grammar, the shell, and the position law (kernel edition).
+ *
+ * ONE system (Arman, 2026-08-23): the Matrx Envelope/Directive protocol and the
+ * Content IR kind system are one system. A directive is an ordinary kind
+ * instance — `{ "__kind": "directive_v1_<class>_<noun>", "items": [...] }` —
+ * whose registered shape additionally carries execution semantics on the
+ * server. This module is the PURE half, ported verbatim from the aidream source
+ * of record (`packages/matrx-graph/matrx_graph/content_ir/directives.py`) so
+ * every UI parses the grammar identically. It lives in the KERNEL because a
+ * host that can parse a kind must be able to recognise a directive without a
+ * second copy of these rules (matrx-frontend carried the only copy until
+ * 2026-09-08; Workflow Studio had none and rendered directives as raw text).
+ *
+ * THE SLUG GRAMMAR — `directive_v<version>_<class>_<noun>`:
+ *  - `directive_v` is a RESERVED prefix; a hand-authored kind may never claim it.
+ *  - `<class>` comes from a CLOSED vocabulary, so parsing is unambiguous even
+ *    though nouns contain underscores: `directive_v1_reference_create_task` is
+ *    `(reference, "create_task")`.
+ *  - capability is DERIVED from the class, never stored twice.
+ */
+
+/** The reserved slug prefix. ANY kind slug starting with this belongs to the Kind Directives protocol. */
+declare const RESERVED_PREFIX: "directive_v";
+/** Current directive grammar version. */
+declare const DIRECTIVE_VERSION: 1;
+/** The full prefix of a v1 directive slug. */
+declare const SLUG_PREFIX: "directive_v1_";
+/** The CLOSED class vocabulary. Closed is what makes the grammar parseable. */
+declare const CLASSES: readonly ["reference", "view", "create", "update", "delete", "action", "validation", "secret"];
+type DirectiveClass = (typeof CLASSES)[number];
+type DirectiveCapability = "pure" | "sensitive" | "side_effect";
+/** class → capability. DERIVED, never stored on a shape. */
+declare const CAPABILITY_BY_CLASS: Readonly<Record<DirectiveClass, DirectiveCapability>>;
+/** The classes that EXECUTE at an agent's output root — a durable side effect. */
+declare const SIDE_EFFECT_CLASSES: ReadonlySet<DirectiveClass>;
+/**
+ * The classes that resolve to a LIVE VALUE inside content. STRICT BY CHOICE,
+ * mirroring the server: exactly `reference` + `secret`.
+ */
+declare const IN_CONTENT_CLASSES: ReadonlySet<DirectiveClass>;
+/** A parsed directive slug. `slug` round-trips through `buildDirectiveSlug`. */
+interface DirectiveSlug {
+    slug: string;
+    version: number;
+    directiveClass: DirectiveClass;
+    noun: string;
+    capability: DirectiveCapability;
+    /** Executes at an agent's output root (THE position law, half one). */
+    executes: boolean;
+    /** Resolves to a live value inside content (THE position law, half two). */
+    inContent: boolean;
+}
+declare function isDirectiveClass(value: unknown): value is DirectiveClass;
+/**
+ * Whether `slug` sits in the reserved Kind Directives namespace. Deliberately
+ * broader than {@link parseDirectiveSlug}: a MALFORMED `directive_v…` slug is
+ * still reserved, so authoring gates reject it instead of letting a near-miss
+ * through as an ordinary kind.
+ */
+declare function isReservedDirectiveSlug(slug: unknown): slug is string;
+/**
+ * `("create", "task") → "directive_v1_create_task"`. THROWS on a class outside
+ * the closed vocabulary or an ill-formed noun — a slug that cannot be parsed
+ * back must never be mintable.
+ */
+declare function buildDirectiveSlug(directiveClass: string, noun: string, version?: number): string;
+/**
+ * Parse a directive slug, or `null` when `slug` is not one. A slug that IS in
+ * the reserved namespace but does not parse returns `null` too — pair with
+ * {@link isReservedDirectiveSlug} to tell "ordinary kind" from "malformed
+ * directive"; every such caller treats the malformed case as an ERROR.
+ */
+declare function parseDirectiveSlug(slug: unknown): DirectiveSlug | null;
+declare function capabilityOf(directiveClass: DirectiveClass): DirectiveCapability;
+/** THE position law, half one: only a side-effect class executes at an agent's output root. */
+declare function executesAtOutputRoot(directiveClass: string): boolean;
+/** THE position law, half two: only a pointer or a sensitive value resolves to a live value inside content. */
+declare function resolvesInContent(directiveClass: string): boolean;
+/**
+ * The `__kind` of `obj` when it is in the reserved namespace, else null. Reads
+ * the RESERVED namespace, not the parsed grammar, so a malformed directive is
+ * still recognised as a directive (and rejected downstream with a real message).
+ */
+declare function directiveSlugOf(obj: unknown): string | null;
+/** THE detector — a dict whose `__kind` is in the reserved namespace. */
+declare function isKindDirective(obj: unknown): boolean;
+/**
+ * The two-key shell, as it travels on the wire. A TYPE alias, not an interface,
+ * so a shell is structurally assignable to `Record<string, unknown>`.
+ */
+type KindDirectiveShell<Item = Record<string, unknown>> = {
+    /** The slug. Serialized FIRST — see the module doc. */
+    [KIND_KEY]: string;
+    items: Item[];
+};
+/**
+ * Build the two-key shell with `__kind` FIRST. Never hand-assemble the object
+ * literal elsewhere: JS preserves insertion order for string keys, and the
+ * first-key rule is what lets the streaming detector type a directive early.
+ */
+declare function buildKindDirective<Item>(slug: string, items: Item[]): KindDirectiveShell<Item>;
+/**
+ * Mid-stream recognition: the opening of a document whose FIRST key is a
+ * reserved directive slug, before the closing brace has arrived. Used by
+ * content splitters so a streaming envelope is typed early.
+ */
+declare function looksLikeDirectiveHead(content: string): boolean;
+
+/**
+ * Decode a Kind Directive — THE one entry point on every client.
+ *
+ * `decodeDirective()` recognises the shell (current OR, for stored content
+ * only, the retired 4-key one), reads the slug, and derives class + noun. A
+ * caller only ever sees a parsed {@link DecodedDirective}; nothing downstream
+ * inspects a raw shell again.
+ *
+ * ITEM VALIDATION IS THE SERVER'S. The registered item models live in aidream
+ * (`services/content_ir_directives/registry.py`) and validate on apply; a
+ * client-side copy of ~120 item models is exactly the drift the merge exists
+ * to kill. The client parses identity, routes, and renders. Mirror of aidream
+ * `services/content_ir_directives/decode.py`.
+ */
+
+/**
+ * A well-formed-looking directive that cannot be honoured (a malformed slug, or
+ * a retired shell that does not map onto the grammar). Never thrown for "this
+ * isn't a directive" — that is `null`.
+ */
+declare class DirectiveDecodeError extends Error {
+    constructor(message: string);
+}
+interface DecodedDirective {
+    /** The parsed slug — class, noun, capability and the position law. */
+    readonly parsed: DirectiveSlug;
+    readonly slug: string;
+    readonly directiveClass: DirectiveClass;
+    readonly noun: string;
+    readonly items: Record<string, unknown>[];
+    /** The two-key shell, normalised — what a confirm POST round-trips. */
+    readonly shell: Record<string, unknown>;
+    /** True when this arrived in the retired 4-key shell and was translated. */
+    readonly legacyShell: boolean;
+}
+/**
+ * A typed directive, or `null` when `value` is not a directive at all. Throws
+ * {@link DirectiveDecodeError} when it IS one but cannot be honoured.
+ */
+declare function decodeDirective(value: unknown): DecodedDirective | null;
+/**
+ * The forgiving read used at render seams: `decodeDirective`, but a directive
+ * that cannot be honoured comes back as `null` after the reason is handed to
+ * `onError`. A render seam must never take a whole message block down over one
+ * bad fence — but it must never swallow the reason either.
+ */
+declare function tryDecodeDirective(value: unknown, onError?: (message: string) => void): DecodedDirective | null;
+/** `decodeDirective` over a JSON string or an already-parsed value. Non-JSON text is `null`. */
+declare function tryDecodeDirectiveContent(content: unknown, onError?: (message: string) => void): DecodedDirective | null;
+
+/**
+ * THE ONE LEGACY SURFACE of the Kind Directives protocol — read-only.
+ *
+ * Stored content written before 2026-08-23 carries the retired 4-key shell
+ * (`matrx_version` / `kind` / `type` / `items`). This module translates it into
+ * the current two-key shell so `decodeDirective` sees one shape, forever. It
+ * never emits, never registers a shape, has no fallback branch, and every use
+ * is counted so the containment can be measured. Only `decode.ts` may import
+ * it (matrx-frontend's `check-legacy-shim-containment` and aidream's
+ * `test_legacy_shim_containment.py` enforce the mirror).
+ */
+declare function legacyShellUses(): number;
+declare function resetLegacyShellUses(): void;
+/** True ONLY for a genuine retired-shell directive claim (sentinel + a retired kind token). */
+declare function isLegacyShell(obj: unknown): boolean;
+
+/**
+ * THE AUTO-VIEW's naming half: every enrolled noun "instantly has a view" —
+ * the prefix rule gives it a renderer, and this gives it a NAME. A shape the
+ * client has never heard of must still read as "Create Agent · Agents", never
+ * as the raw `agent` token and never as a slug.
+ *
+ * The catalog (`platform.entity_types` → the server's directive catalog) is the
+ * authority for `label` / `family` / `title_column`; a host that mirrors it
+ * passes a {@link DirectiveNounCatalog}. Without one — or for a noun the
+ * catalog does not carry (a Kind Action like `plan_tree`) — the name degrades
+ * to a title-cased token: legible, honestly derived, never blank.
+ */
+
+interface DirectiveNounEntry {
+    /** The noun's human name — "Agent", "Plan tree". */
+    label?: string | null;
+    /** The catalog family ("Agents"). */
+    family?: string | null;
+    /** Which field of a row names it (`name`, `title`, …). */
+    titleColumn?: string | null;
+}
+/** A host-supplied lookup over the mirrored catalog. `undefined` = not carried. */
+type DirectiveNounCatalog = (noun: string) => DirectiveNounEntry | undefined;
+interface DirectiveDisplay {
+    /** The noun's human name — "Agent", "Plan tree". */
+    noun: string;
+    /** The catalog family ("Agents"), or "" when the catalog has none. */
+    family: string;
+    /** What this directive DOES, in the user's words — "Create", "Reference". */
+    action: string;
+    /** One line: "Create Agent". */
+    title: string;
+}
+/** `plan_node_patch` → `Plan node patch`. The honest last resort. */
+declare function titleCaseToken(token: string): string;
+/**
+ * How a class reads to a human. `action` is deliberately "Run": a Kind Action
+ * is a named procedure, and "Action Plan tree" reads like a noun phrase where a
+ * verb belongs. Mirrored by the server's kind-catalog label.
+ */
+declare const ACTION_BY_CLASS: Readonly<Record<DirectiveClass, string>>;
+declare function nounLabel(noun: string, catalog?: DirectiveNounCatalog): string;
+declare function nounFamily(noun: string, catalog?: DirectiveNounCatalog): string;
+declare function nounTitleColumn(noun: string, catalog?: DirectiveNounCatalog): string | null;
+/** Everything a generic card needs to name a directive it cannot render. */
+declare function directiveDisplay(directiveClass: DirectiveClass, noun: string, catalog?: DirectiveNounCatalog): DirectiveDisplay;
+
+/**
+ * Naming and summarising ONE item of a directive, for the compact card.
+ *
+ * THE RULE: a user is never asked to approve a write they cannot identify. The
+ * card must say WHAT is about to be created/updated/deleted, derived from
+ * authority rather than guesswork, in this order:
+ *   1. the noun's catalog `title_column` — the server's own answer to "what
+ *      names a row of this table";
+ *   2. the conventional identity fields, in a fixed order;
+ *   3. the honest last resort — "Item 2 of 3", never a blank chip and never a
+ *      slug pretending to be a name.
+ *
+ * Facts are scalars ONLY. Nesting goes to the panel, never into the row.
+ */
+/**
+ * What to call this item. `titleColumn` is the noun's catalog title column
+ * (consulted first); null when the catalog carries none.
+ */
+declare function itemTitle(item: Record<string, unknown>, titleColumn: string | null, index: number, total: number): string;
+/** A one-line subtitle when the item carries prose about itself. */
+declare function itemSubtitle(item: Record<string, unknown>): string | null;
+interface ItemFact {
+    key: string;
+    label: string;
+    value: string;
+}
+/**
+ * Up to `limit` scalar facts about the item — counts for collections, values
+ * for scalars. Nested objects are deliberately absent (they belong in the
+ * panel), and so is anything already carried by the title/subtitle.
+ */
+declare function itemFacts(item: Record<string, unknown>, limit?: number): ItemFact[];
+
+/**
+ * THE DIRECTIVE⇄KIND SEAM, client side.
+ *
+ * Arman, 2026-08-26: the envelope / Matrx-Actions system and the Shape (kind)
+ * system are ONE system with several methods inside it. They meet at the ITEM.
+ * A directive is a CONTAINER; its items are the payload, and when the server's
+ * item model is already a `KindModel`, that payload IS a registered kind
+ * instance — so the kind system already knows how to validate, render and copy
+ * it.
+ *
+ * The seam is SERVER-DERIVED (`ShapeSpec.item_kind`). Since 2026-09-08 the ONE
+ * kind endpoint publishes every directive shape as a KindDescriptor whose
+ * `items` EDGE names the item kind, so a client reads it from the same
+ * catalog it already holds — {@link directiveItemKindFromEdges}. A host that
+ * mirrors the directive catalog manifest instead passes its map as a
+ * {@link DirectiveItemKindLookup}. `null` is HONEST, never a gap-filler.
+ */
+/** A host-supplied lookup: slug → the kind ONE item is, or null. */
+type DirectiveItemKindLookup = (slug: string) => string | null;
+/** The `items` edge of a directive KindDescriptor, as the kind catalog serves it. */
+interface DirectiveItemsEdge {
+    field_name?: string;
+    fieldPath?: string;
+    child_kind?: string;
+    childKind?: string;
+}
+/** The item kind named by a directive descriptor's `items` edge, or null. */
+declare function directiveItemKindFromEdges(edges: readonly DirectiveItemsEdge[] | null | undefined): string | null;
+/**
+ * The item, presented the way the kind pipeline expects it: `__kind` FIRST so a
+ * consumer types the object from its own first key. `__kind` is ADDED, never
+ * overwritten: an item that already carries its marker keeps the value it was
+ * emitted with. Null when no kind is known — the caller owns the generic floor.
+ */
+declare function asKindInstance(item: Record<string, unknown>, kind: string | null): Record<string, unknown> | null;
+
+export { ACTION_BY_CLASS, CAPABILITY_BY_CLASS, CLASSES, DIRECTIVE_VERSION, type DecodedDirective, type DirectiveCapability, type DirectiveClass, DirectiveDecodeError, type DirectiveDisplay, type DirectiveItemKindLookup, type DirectiveItemsEdge, type DirectiveNounCatalog, type DirectiveNounEntry, type DirectiveSlug, IN_CONTENT_CLASSES, type ItemFact, KIND_KEY, type KindDirectiveShell, RESERVED_PREFIX, SIDE_EFFECT_CLASSES, SLUG_PREFIX, asKindInstance, buildDirectiveSlug, buildKindDirective, capabilityOf, decodeDirective, directiveDisplay, directiveItemKindFromEdges, directiveSlugOf, executesAtOutputRoot, isDirectiveClass, isKindDirective, isLegacyShell, isReservedDirectiveSlug, itemFacts, itemSubtitle, itemTitle, legacyShellUses, looksLikeDirectiveHead, nounFamily, nounLabel, nounTitleColumn, parseDirectiveSlug, resetLegacyShellUses, resolvesInContent, titleCaseToken, tryDecodeDirective, tryDecodeDirectiveContent };