@ai-matrx/content-ir-react 0.13.18 → 0.15.0

package/dist/{route-DxK1SoPh.d.cts → route-BCtPhF7W.d.cts}

@@ -17,6 +17,25 @@ interface DirectiveApplyResult {
      */
     records?: DirectiveRecordRef[];
 }
+/**
+ * What the server's action ledger says about ONE block, read on mount so a
+ * reloaded page never offers "Apply" for work that already ran (reviewer
+ * defect 5, 2026-10-02).
+ *
+ *  - `not_applied` — still to do (or partly done: the batch re-applies, and the
+ *    server replays the members it already holds). The card offers Apply.
+ *  - `in_flight` — another request is applying it right now. The card says it
+ *    is finishing and asks again shortly; it offers neither Apply nor a tally.
+ *  - `applied` — the ledger holds every item. The card shows the tally exactly
+ *    as a fresh apply would: the ledger's own sentence and the records, as doors.
+ */
+interface DirectiveApplyState {
+    state: "not_applied" | "in_flight" | "applied";
+    /** The ledger row's sentence ("Created task."), never composed client-side. */
+    message?: string | null;
+    /** The records the original apply wrote — the tally's doors. */
+    records?: DirectiveRecordRef[];
+}
 /** One record a directive names: the noun it is, and its id. */
 interface DirectiveRecordRef {
     noun: string;
@@ -43,6 +62,28 @@ interface DirectiveAskRequest {
     items: Record<string, unknown>[];
     /** The noun's human label ("Task"), from the host's catalog when it has one. */
     nounLabel: string;
+    /**
+     * True for "Run again": the ledger already holds this block, and a yes runs
+     * it a SECOND time (`force`) — another copy for a create, the same fields
+     * written again for an update, another delete for a restored record. The
+     * question must say so.
+     */
+    again?: boolean;
+}
+/**
+ * The shell a card hands its host — the two keys, plus WHERE it sits.
+ *
+ * `conversationId` is the conversation the card renders in (a chat message),
+ * absent in a person's own content (a note). It is the idempotency NAMESPACE:
+ * a card in an agent's message must apply under the SAME key as that
+ * proposal's Approve button, or the one action could run twice.
+ */
+interface DirectiveShell {
+    __kind: string;
+    items: Record<string, unknown>[];
+    conversationId?: string;
+    /** "Run again": skip the ledger's dedup and apply a second time. */
+    force?: boolean;
 }
 interface DirectiveOpenItemOptions {
     /** The item, `__kind`-stamped when the shape has an item kind. */
@@ -71,10 +112,7 @@ interface DirectiveHost {
      * item against the registered model and runs the ONE handler; idempotent).
      * Reject with an Error whose message is safe to show.
      */
-    confirm?: (shell: {
-        __kind: string;
-        items: Record<string, unknown>[];
-    }) => Promise<DirectiveApplyResult>;
+    confirm?: (shell: DirectiveShell) => Promise<DirectiveApplyResult>;
     /**
      * Ask the person BEFORE anything runs, naming the consequence (the records,
      * what changes). Resolve `true` to go ahead, `false` to leave the card as it
@@ -84,6 +122,17 @@ interface DirectiveHost {
      * will read "Applying…" while its dialog is up).
      */
     ask?: (request: DirectiveAskRequest) => Promise<boolean>;
+    /**
+     * Has this exact block already been applied? Read ONCE when the card mounts
+     * (and again while the answer is `in_flight`), so the card survives a reload:
+     * the server ledger, not component state, is what knows. The identity is the
+     * server's (it hashes the validated items in the same namespace `confirm`
+     * applies in), so a host asks — it never computes. Batch on the host side if
+     * a page carries many cards. Reject with an Error when the ledger cannot be
+     * read: the card reports it and offers Apply, which is safe because `confirm`
+     * is idempotent. Absent → the card starts at Apply, as before.
+     */
+    applyState?: (shell: DirectiveShell) => Promise<DirectiveApplyState>;
     /**
      * Draw ONE existing record by its live name, as a way to open it. Used on
      * update/delete rows (the record that will change), in the host's own ask
@@ -102,6 +151,20 @@ interface DirectiveHost {
     /** Where a decode failure or an unhonourable shell is reported. Default: console.error. */
     reportError?: (message: string) => void;
 }
+/** Where a directive renders — today, the conversation it sits in (if any). */
+interface DirectiveScope {
+    conversationId?: string | null;
+}
+/**
+ * Tell every card below WHERE it renders. A host draws a chat message's
+ * directives inside one of these (or passes `conversationId` to
+ * `DirectiveRender`), so the card applies in that conversation's namespace —
+ * the same key the agent's proposal approves under. A note mounts none.
+ */
+declare function DirectiveScopeProvider({ conversationId, children, }: DirectiveScope & {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function useDirectiveScope(): DirectiveScope;
 interface DirectiveHostProviderProps {
     host: DirectiveHost;
     children: ReactNode;
@@ -602,4 +665,4 @@ interface KindRouteBinding {
 /** Bind the pure routes to one host's env + owned block types. */
 declare function createKindRouteBinding(env: KindRouteEnv, options?: KindRouteOptions): KindRouteBinding;
 
-export { kindServerDataFromStoredValue as A, markKindPartialUnsafe as B, type ContentIrHost as C, DB_KIND_COMPONENT_KEY as D, readIrRouteMarker as E, resetPartialUnsafeKinds as F, GENERIC_STRUCTURED_COMPONENT_KEY as G, resetSourcelessDbRowReports as H, IR_PROVISIONAL_KEY as I, resolveAnnouncedKindLoading as J, type KindRouteEnv as K, resolveProvisionalKindRender as L, resolveSupersededKindRender as M, routeEnvOf as N, useDirectiveHost as O, type PartialRenderOptions as P, type StructuredValueRenderProps as S, type KindDefinitionSource as a, type ContentIrRenderSeams as b, DIRECTIVE_BLOCK_TYPE as c, type DirectiveApplyResult as d, type DirectiveAskRequest as e, type DirectiveCopyProps as f, type DirectiveHost as g, DirectiveHostProvider as h, type DirectiveHostProviderProps as i, type DirectiveOpenItemOptions as j, type DirectiveRecordProps as k, type DirectiveRecordRef as l, type GenericFallbackReason as m, IR_ROUTE_KEY as n, type IrRenderBlock as o, type IrRoutableBlock as p, type IrRouteMarker as q, type KindRouteBinding as r, type KindRouteOptions as s, type ProvisionalKindRender as t, type SupersededKindRender as u, applyIrKindRoute as v, createKindRouteBinding as w, envelopeFromPartialKind as x, isPartialReadyKind as y, isProvisionalBlock as z };
+export { createKindRouteBinding as A, envelopeFromPartialKind as B, type ContentIrHost as C, DB_KIND_COMPONENT_KEY as D, isPartialReadyKind as E, isProvisionalBlock as F, GENERIC_STRUCTURED_COMPONENT_KEY as G, kindServerDataFromStoredValue as H, IR_PROVISIONAL_KEY as I, markKindPartialUnsafe as J, type KindRouteEnv as K, readIrRouteMarker as L, resetPartialUnsafeKinds as M, resetSourcelessDbRowReports as N, resolveAnnouncedKindLoading as O, type PartialRenderOptions as P, resolveProvisionalKindRender as Q, resolveSupersededKindRender as R, type StructuredValueRenderProps as S, routeEnvOf as T, useDirectiveHost as U, useDirectiveScope as V, type KindDefinitionSource as a, type ContentIrRenderSeams as b, DIRECTIVE_BLOCK_TYPE as c, type DirectiveApplyResult as d, type DirectiveApplyState as e, type DirectiveAskRequest as f, type DirectiveCopyProps as g, type DirectiveHost as h, DirectiveHostProvider as i, type DirectiveHostProviderProps as j, type DirectiveOpenItemOptions as k, type DirectiveRecordProps as l, type DirectiveRecordRef as m, type DirectiveScope as n, DirectiveScopeProvider as o, type DirectiveShell as p, type GenericFallbackReason as q, IR_ROUTE_KEY as r, type IrRenderBlock as s, type IrRoutableBlock as t, type IrRouteMarker as u, type KindRouteBinding as v, type KindRouteOptions as w, type ProvisionalKindRender as x, type SupersededKindRender as y, applyIrKindRoute as z };

package/dist/{route-JGZfl2nL.d.ts → route-DDbgc-ID.d.ts}

@@ -17,6 +17,25 @@ interface DirectiveApplyResult {
      */
     records?: DirectiveRecordRef[];
 }
+/**
+ * What the server's action ledger says about ONE block, read on mount so a
+ * reloaded page never offers "Apply" for work that already ran (reviewer
+ * defect 5, 2026-10-02).
+ *
+ *  - `not_applied` — still to do (or partly done: the batch re-applies, and the
+ *    server replays the members it already holds). The card offers Apply.
+ *  - `in_flight` — another request is applying it right now. The card says it
+ *    is finishing and asks again shortly; it offers neither Apply nor a tally.
+ *  - `applied` — the ledger holds every item. The card shows the tally exactly
+ *    as a fresh apply would: the ledger's own sentence and the records, as doors.
+ */
+interface DirectiveApplyState {
+    state: "not_applied" | "in_flight" | "applied";
+    /** The ledger row's sentence ("Created task."), never composed client-side. */
+    message?: string | null;
+    /** The records the original apply wrote — the tally's doors. */
+    records?: DirectiveRecordRef[];
+}
 /** One record a directive names: the noun it is, and its id. */
 interface DirectiveRecordRef {
     noun: string;
@@ -43,6 +62,28 @@ interface DirectiveAskRequest {
     items: Record<string, unknown>[];
     /** The noun's human label ("Task"), from the host's catalog when it has one. */
     nounLabel: string;
+    /**
+     * True for "Run again": the ledger already holds this block, and a yes runs
+     * it a SECOND time (`force`) — another copy for a create, the same fields
+     * written again for an update, another delete for a restored record. The
+     * question must say so.
+     */
+    again?: boolean;
+}
+/**
+ * The shell a card hands its host — the two keys, plus WHERE it sits.
+ *
+ * `conversationId` is the conversation the card renders in (a chat message),
+ * absent in a person's own content (a note). It is the idempotency NAMESPACE:
+ * a card in an agent's message must apply under the SAME key as that
+ * proposal's Approve button, or the one action could run twice.
+ */
+interface DirectiveShell {
+    __kind: string;
+    items: Record<string, unknown>[];
+    conversationId?: string;
+    /** "Run again": skip the ledger's dedup and apply a second time. */
+    force?: boolean;
 }
 interface DirectiveOpenItemOptions {
     /** The item, `__kind`-stamped when the shape has an item kind. */
@@ -71,10 +112,7 @@ interface DirectiveHost {
      * item against the registered model and runs the ONE handler; idempotent).
      * Reject with an Error whose message is safe to show.
      */
-    confirm?: (shell: {
-        __kind: string;
-        items: Record<string, unknown>[];
-    }) => Promise<DirectiveApplyResult>;
+    confirm?: (shell: DirectiveShell) => Promise<DirectiveApplyResult>;
     /**
      * Ask the person BEFORE anything runs, naming the consequence (the records,
      * what changes). Resolve `true` to go ahead, `false` to leave the card as it
@@ -84,6 +122,17 @@ interface DirectiveHost {
      * will read "Applying…" while its dialog is up).
      */
     ask?: (request: DirectiveAskRequest) => Promise<boolean>;
+    /**
+     * Has this exact block already been applied? Read ONCE when the card mounts
+     * (and again while the answer is `in_flight`), so the card survives a reload:
+     * the server ledger, not component state, is what knows. The identity is the
+     * server's (it hashes the validated items in the same namespace `confirm`
+     * applies in), so a host asks — it never computes. Batch on the host side if
+     * a page carries many cards. Reject with an Error when the ledger cannot be
+     * read: the card reports it and offers Apply, which is safe because `confirm`
+     * is idempotent. Absent → the card starts at Apply, as before.
+     */
+    applyState?: (shell: DirectiveShell) => Promise<DirectiveApplyState>;
     /**
      * Draw ONE existing record by its live name, as a way to open it. Used on
      * update/delete rows (the record that will change), in the host's own ask
@@ -102,6 +151,20 @@ interface DirectiveHost {
     /** Where a decode failure or an unhonourable shell is reported. Default: console.error. */
     reportError?: (message: string) => void;
 }
+/** Where a directive renders — today, the conversation it sits in (if any). */
+interface DirectiveScope {
+    conversationId?: string | null;
+}
+/**
+ * Tell every card below WHERE it renders. A host draws a chat message's
+ * directives inside one of these (or passes `conversationId` to
+ * `DirectiveRender`), so the card applies in that conversation's namespace —
+ * the same key the agent's proposal approves under. A note mounts none.
+ */
+declare function DirectiveScopeProvider({ conversationId, children, }: DirectiveScope & {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function useDirectiveScope(): DirectiveScope;
 interface DirectiveHostProviderProps {
     host: DirectiveHost;
     children: ReactNode;
@@ -602,4 +665,4 @@ interface KindRouteBinding {
 /** Bind the pure routes to one host's env + owned block types. */
 declare function createKindRouteBinding(env: KindRouteEnv, options?: KindRouteOptions): KindRouteBinding;
 
-export { kindServerDataFromStoredValue as A, markKindPartialUnsafe as B, type ContentIrHost as C, DB_KIND_COMPONENT_KEY as D, readIrRouteMarker as E, resetPartialUnsafeKinds as F, GENERIC_STRUCTURED_COMPONENT_KEY as G, resetSourcelessDbRowReports as H, IR_PROVISIONAL_KEY as I, resolveAnnouncedKindLoading as J, type KindRouteEnv as K, resolveProvisionalKindRender as L, resolveSupersededKindRender as M, routeEnvOf as N, useDirectiveHost as O, type PartialRenderOptions as P, type StructuredValueRenderProps as S, type KindDefinitionSource as a, type ContentIrRenderSeams as b, DIRECTIVE_BLOCK_TYPE as c, type DirectiveApplyResult as d, type DirectiveAskRequest as e, type DirectiveCopyProps as f, type DirectiveHost as g, DirectiveHostProvider as h, type DirectiveHostProviderProps as i, type DirectiveOpenItemOptions as j, type DirectiveRecordProps as k, type DirectiveRecordRef as l, type GenericFallbackReason as m, IR_ROUTE_KEY as n, type IrRenderBlock as o, type IrRoutableBlock as p, type IrRouteMarker as q, type KindRouteBinding as r, type KindRouteOptions as s, type ProvisionalKindRender as t, type SupersededKindRender as u, applyIrKindRoute as v, createKindRouteBinding as w, envelopeFromPartialKind as x, isPartialReadyKind as y, isProvisionalBlock as z };
+export { createKindRouteBinding as A, envelopeFromPartialKind as B, type ContentIrHost as C, DB_KIND_COMPONENT_KEY as D, isPartialReadyKind as E, isProvisionalBlock as F, GENERIC_STRUCTURED_COMPONENT_KEY as G, kindServerDataFromStoredValue as H, IR_PROVISIONAL_KEY as I, markKindPartialUnsafe as J, type KindRouteEnv as K, readIrRouteMarker as L, resetPartialUnsafeKinds as M, resetSourcelessDbRowReports as N, resolveAnnouncedKindLoading as O, type PartialRenderOptions as P, resolveProvisionalKindRender as Q, resolveSupersededKindRender as R, type StructuredValueRenderProps as S, routeEnvOf as T, useDirectiveHost as U, useDirectiveScope as V, type KindDefinitionSource as a, type ContentIrRenderSeams as b, DIRECTIVE_BLOCK_TYPE as c, type DirectiveApplyResult as d, type DirectiveApplyState as e, type DirectiveAskRequest as f, type DirectiveCopyProps as g, type DirectiveHost as h, DirectiveHostProvider as i, type DirectiveHostProviderProps as j, type DirectiveOpenItemOptions as k, type DirectiveRecordProps as l, type DirectiveRecordRef as m, type DirectiveScope as n, DirectiveScopeProvider as o, type DirectiveShell as p, type GenericFallbackReason as q, IR_ROUTE_KEY as r, type IrRenderBlock as s, type IrRoutableBlock as t, type IrRouteMarker as u, type KindRouteBinding as v, type KindRouteOptions as w, type ProvisionalKindRender as x, type SupersededKindRender as y, applyIrKindRoute as z };

package/dist/route.d.cts

@@ -1,4 +1,4 @@
-export { D as DB_KIND_COMPONENT_KEY, c as DIRECTIVE_BLOCK_TYPE, G as GENERIC_STRUCTURED_COMPONENT_KEY, m as GenericFallbackReason, I as IR_PROVISIONAL_KEY, n as IR_ROUTE_KEY, q as IrRouteMarker, r as KindRouteBinding, s as KindRouteOptions, P as PartialRenderOptions, t as ProvisionalKindRender, u as SupersededKindRender, v as applyIrKindRoute, w as createKindRouteBinding, x as envelopeFromPartialKind, y as isPartialReadyKind, z as isProvisionalBlock, A as kindServerDataFromStoredValue, B as markKindPartialUnsafe, E as readIrRouteMarker, F as resetPartialUnsafeKinds, H as resetSourcelessDbRowReports, J as resolveAnnouncedKindLoading, L as resolveProvisionalKindRender, M as resolveSupersededKindRender } from './route-DxK1SoPh.cjs';
+export { D as DB_KIND_COMPONENT_KEY, c as DIRECTIVE_BLOCK_TYPE, G as GENERIC_STRUCTURED_COMPONENT_KEY, q as GenericFallbackReason, I as IR_PROVISIONAL_KEY, r as IR_ROUTE_KEY, u as IrRouteMarker, v as KindRouteBinding, w as KindRouteOptions, P as PartialRenderOptions, x as ProvisionalKindRender, y as SupersededKindRender, z as applyIrKindRoute, A as createKindRouteBinding, B as envelopeFromPartialKind, E as isPartialReadyKind, F as isProvisionalBlock, H as kindServerDataFromStoredValue, J as markKindPartialUnsafe, L as readIrRouteMarker, M as resetPartialUnsafeKinds, N as resetSourcelessDbRowReports, O as resolveAnnouncedKindLoading, Q as resolveProvisionalKindRender, R as resolveSupersededKindRender } from './route-BCtPhF7W.cjs';
 import './component-resolution.types-DLO2w-0n.cjs';
 import 'react';
 import '@ai-matrx/content-ir';

package/dist/route.d.ts

@@ -1,4 +1,4 @@
-export { D as DB_KIND_COMPONENT_KEY, c as DIRECTIVE_BLOCK_TYPE, G as GENERIC_STRUCTURED_COMPONENT_KEY, m as GenericFallbackReason, I as IR_PROVISIONAL_KEY, n as IR_ROUTE_KEY, q as IrRouteMarker, r as KindRouteBinding, s as KindRouteOptions, P as PartialRenderOptions, t as ProvisionalKindRender, u as SupersededKindRender, v as applyIrKindRoute, w as createKindRouteBinding, x as envelopeFromPartialKind, y as isPartialReadyKind, z as isProvisionalBlock, A as kindServerDataFromStoredValue, B as markKindPartialUnsafe, E as readIrRouteMarker, F as resetPartialUnsafeKinds, H as resetSourcelessDbRowReports, J as resolveAnnouncedKindLoading, L as resolveProvisionalKindRender, M as resolveSupersededKindRender } from './route-JGZfl2nL.js';
+export { D as DB_KIND_COMPONENT_KEY, c as DIRECTIVE_BLOCK_TYPE, G as GENERIC_STRUCTURED_COMPONENT_KEY, q as GenericFallbackReason, I as IR_PROVISIONAL_KEY, r as IR_ROUTE_KEY, u as IrRouteMarker, v as KindRouteBinding, w as KindRouteOptions, P as PartialRenderOptions, x as ProvisionalKindRender, y as SupersededKindRender, z as applyIrKindRoute, A as createKindRouteBinding, B as envelopeFromPartialKind, E as isPartialReadyKind, F as isProvisionalBlock, H as kindServerDataFromStoredValue, J as markKindPartialUnsafe, L as readIrRouteMarker, M as resetPartialUnsafeKinds, N as resetSourcelessDbRowReports, O as resolveAnnouncedKindLoading, Q as resolveProvisionalKindRender, R as resolveSupersededKindRender } from './route-DDbgc-ID.js';
 import './component-resolution.types-DLO2w-0n.js';
 import 'react';
 import '@ai-matrx/content-ir';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/content-ir-react",
-  "version": "0.13.18",
+  "version": "0.15.0",
   "description": "The shared AI Matrx Content IR RENDER layer: kind routing, the component resolver, provisional (streaming) rendering, the runtime-wrapper chrome, and the generic structured floor — as portable React.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -124,8 +124,8 @@
     "react": ">=19.0.0"
   },
   "dependencies": {
-    "@ai-matrx/kit": "latest",
-    "@ai-matrx/content-ir": "latest"
+    "@ai-matrx/content-ir": "latest",
+    "@ai-matrx/kit": "latest"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",