@ai-matrx/alchemy 0.8.60 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +3 -0
  3. package/dist/actions.cjs +1 -1
  4. package/dist/actions.cjs.map +1 -1
  5. package/dist/actions.d.cts +465 -4
  6. package/dist/actions.d.ts +465 -4
  7. package/dist/actions.js +1 -1
  8. package/dist/actions.js.map +1 -1
  9. package/dist/checks.cjs +1 -1
  10. package/dist/checks.cjs.map +1 -1
  11. package/dist/checks.d.cts +22 -1
  12. package/dist/checks.d.ts +22 -1
  13. package/dist/checks.js +2 -2
  14. package/dist/checks.js.map +1 -1
  15. package/dist/core.cjs +1 -1
  16. package/dist/core.cjs.map +1 -1
  17. package/dist/core.d.cts +283 -39
  18. package/dist/core.d.ts +283 -39
  19. package/dist/core.js +2 -2
  20. package/dist/core.js.map +1 -1
  21. package/dist/declare.cjs +1 -1
  22. package/dist/declare.cjs.map +1 -1
  23. package/dist/declare.d.cts +12 -4
  24. package/dist/declare.d.ts +12 -4
  25. package/dist/declare.js +1 -1
  26. package/dist/declare.js.map +1 -1
  27. package/dist/index.cjs +1 -1
  28. package/dist/index.cjs.map +1 -1
  29. package/dist/index.d.cts +283 -39
  30. package/dist/index.d.ts +283 -39
  31. package/dist/index.js +2 -2
  32. package/dist/index.js.map +1 -1
  33. package/dist/menu.cjs +1 -1
  34. package/dist/menu.cjs.map +1 -1
  35. package/dist/menu.d.cts +262 -3
  36. package/dist/menu.d.ts +262 -3
  37. package/dist/menu.js +1 -1
  38. package/dist/menu.js.map +1 -1
  39. package/dist/operate-server.d.cts +11 -1
  40. package/dist/operate-server.d.ts +11 -1
  41. package/dist/operate.cjs +1 -1
  42. package/dist/operate.cjs.map +1 -1
  43. package/dist/operate.d.cts +283 -39
  44. package/dist/operate.d.ts +283 -39
  45. package/dist/operate.js +2 -2
  46. package/dist/operate.js.map +1 -1
  47. package/dist/ports.cjs.map +1 -1
  48. package/dist/ports.d.cts +269 -2
  49. package/dist/ports.d.ts +269 -2
  50. package/dist/react-bar.cjs +1 -1
  51. package/dist/react-bar.cjs.map +1 -1
  52. package/dist/react-bar.d.cts +4 -2
  53. package/dist/react-bar.d.ts +4 -2
  54. package/dist/react-bar.js +1 -1
  55. package/dist/react-bar.js.map +1 -1
  56. package/dist/react-host.d.cts +262 -3
  57. package/dist/react-host.d.ts +262 -3
  58. package/dist/react-menu.cjs +1 -1
  59. package/dist/react-menu.cjs.map +1 -1
  60. package/dist/react-menu.d.cts +4 -2
  61. package/dist/react-menu.d.ts +4 -2
  62. package/dist/react-menu.js +1 -1
  63. package/dist/react-menu.js.map +1 -1
  64. package/dist/react-overflow.cjs +1 -1
  65. package/dist/react-overflow.cjs.map +1 -1
  66. package/dist/react-overflow.d.cts +262 -3
  67. package/dist/react-overflow.d.ts +262 -3
  68. package/dist/react-overflow.js +1 -1
  69. package/dist/react-overflow.js.map +1 -1
  70. package/dist/react-palette.cjs +1 -1
  71. package/dist/react-palette.cjs.map +1 -1
  72. package/dist/react-palette.d.cts +4 -2
  73. package/dist/react-palette.d.ts +4 -2
  74. package/dist/react-palette.js +1 -1
  75. package/dist/react-palette.js.map +1 -1
  76. package/dist/react-selection.cjs +1 -1
  77. package/dist/react-selection.cjs.map +1 -1
  78. package/dist/react-selection.d.cts +4 -2
  79. package/dist/react-selection.d.ts +4 -2
  80. package/dist/react-selection.js +1 -1
  81. package/dist/react-selection.js.map +1 -1
  82. package/dist/react-sheet.cjs +1 -1
  83. package/dist/react-sheet.cjs.map +1 -1
  84. package/dist/react-sheet.d.cts +4 -2
  85. package/dist/react-sheet.d.ts +4 -2
  86. package/dist/react-sheet.js +1 -1
  87. package/dist/react-sheet.js.map +1 -1
  88. package/package.json +1 -1
package/dist/operate.d.ts CHANGED
@@ -2,8 +2,8 @@
2
2
  * Framework-neutral transfer contracts (Alchemy Operate, CONTRACT §2.3). All data crossing this boundary is JSON.
3
3
  * Moved from `@ai-matrx/kit/content-transfer` in ALC-16; the format-adapter contract lives in `./contract`.
4
4
  */
5
- type Json$1 = null | boolean | number | string | Json$1[] | {
6
- [key: string]: Json$1;
5
+ type Json$2 = null | boolean | number | string | Json$2[] | {
6
+ [key: string]: Json$2;
7
7
  };
8
8
  type Payload =
9
9
  /** A text payload may name its language (code blocks): downloads take its extension, Markdown fences it. */
@@ -16,15 +16,15 @@ type Payload =
16
16
  text: string;
17
17
  } | {
18
18
  kind: "json";
19
- value: Json$1;
19
+ value: Json$2;
20
20
  } | {
21
21
  kind: "rows";
22
- rows: Record<string, Json$1>[];
22
+ rows: Record<string, Json$2>[];
23
23
  columns: Column[];
24
24
  } | {
25
25
  kind: "registered";
26
26
  format: string;
27
- value: Json$1;
27
+ value: Json$2;
28
28
  };
29
29
  type Column = {
30
30
  id: string;
@@ -38,9 +38,9 @@ type Column = {
38
38
  dataType?: string;
39
39
  order?: number;
40
40
  required?: boolean;
41
- defaultValue?: Json$1;
42
- validation?: Json$1;
43
- metadata?: Json$1;
41
+ defaultValue?: Json$2;
42
+ validation?: Json$2;
43
+ metadata?: Json$2;
44
44
  };
45
45
  };
46
46
  type ExportProjection = {
@@ -93,21 +93,21 @@ type Snapshot = RawSnapshot & {
93
93
  type QuerySnapshot = {
94
94
  sourceId: string;
95
95
  revision: string;
96
- query: Json$1;
96
+ query: Json$2;
97
97
  order: {
98
98
  field: string;
99
99
  direction: "asc" | "desc";
100
100
  }[];
101
101
  };
102
102
  type ExportPage = {
103
- rows: Record<string, Json$1>[];
103
+ rows: Record<string, Json$2>[];
104
104
  nextCursor: string | null;
105
105
  coverage: Coverage;
106
106
  consistencyToken: string | null;
107
107
  };
108
108
  type CapturedAllMatching = {
109
109
  query: QuerySnapshot;
110
- getRowId(row: Record<string, Json$1>): string;
110
+ getRowId(row: Record<string, Json$2>): string;
111
111
  page(request: {
112
112
  query: QuerySnapshot;
113
113
  cursor: string | null;
@@ -147,7 +147,7 @@ type Draft = {
147
147
  };
148
148
  type Transform = {
149
149
  id: string;
150
- apply(draft: Draft, options: Json$1, signal: AbortSignal): Promise<Draft>;
150
+ apply(draft: Draft, options: Json$2, signal: AbortSignal): Promise<Draft>;
151
151
  };
152
152
  type Artifact = {
153
153
  snapshotId: string;
@@ -338,9 +338,9 @@ type BoundAllMatching = {
338
338
  type NormalizeTransferJsonOptions = {
339
339
  omitUndefinedObjectProperties?: boolean;
340
340
  };
341
- declare function normalizeTransferJson(value: unknown, options?: NormalizeTransferJsonOptions): Json$1;
341
+ declare function normalizeTransferJson(value: unknown, options?: NormalizeTransferJsonOptions): Json$2;
342
342
  /** Column ids are identities, never an alternative data address. */
343
- declare function readTransferCell(row: Record<string, Json$1>, column: Column): Json$1 | undefined;
343
+ declare function readTransferCell(row: Record<string, Json$2>, column: Column): Json$2 | undefined;
344
344
  declare function projectSnapshot(raw: RawSnapshot, projection: ExportProjection): Snapshot;
345
345
  declare function directSource(payload: Payload, options?: Partial<Pick<RawSnapshot, "id" | "sourceId" | "revision" | "label" | "coverage" | "unsavedChanges" | "sections" | "limits"> & {
346
346
  projection: ExportProjection;
@@ -385,7 +385,7 @@ declare function reduceJson(draft: Draft, options: {
385
385
  maxArrayItems?: number | null;
386
386
  }): Draft;
387
387
  declare function collectAllMatching(c: BoundAllMatching, signal: AbortSignal): Promise<{
388
- rows: Record<string, Json$1>[];
388
+ rows: Record<string, Json$2>[];
389
389
  coverage: RawSnapshot["coverage"];
390
390
  omissions: Omission[];
391
391
  error?: ContentTransferError;
@@ -433,6 +433,16 @@ declare function createSurfaceTransferHandle(options: {
433
433
  /** Applies explicit preparation/source limits with exact omissions; token target is advisory. */
434
434
  declare function applyTransferLimits(draft: Draft, limits: Partial<TransferLimits>): Draft;
435
435
 
436
+ /**
437
+ * Matrx Alchemy — Declare types (CONTRACT §2.1).
438
+ *
439
+ * A declaration is plain JSON data (chair ruling N2): no functions, no classes,
440
+ * no React. Runtime behaviour lives in `MountedSurface` (`/declare/host`) and in
441
+ * handler registrations, never here. Zero React, zero `@ai-matrx/agents`.
442
+ */
443
+ type Json$1 = null | boolean | number | string | Json$1[] | {
444
+ [key: string]: Json$1;
445
+ };
436
446
  /** Unchanged from `ui_surface_value_type_chk`. */
437
447
  type ValueType = "string" | "number" | "boolean" | "object" | "array" | "document";
438
448
  type Classification = "ordinary" | "secret" | "credential";
@@ -639,6 +649,196 @@ interface ClickTarget {
639
649
  host?: unknown;
640
650
  }
641
651
 
652
+ /**
653
+ * THE ONE WRITE DOOR (Matrx Alchemy ALC-17; Applets CONTRACTS §6 "receipts through the one write door").
654
+ *
655
+ * Every write — a person's edit, a menu row, a destination send, an agent, an applet, an automation,
656
+ * an Action projected from a write target — lands through `door.write`. The door:
657
+ *
658
+ * 1. resolves the DECLARED write target (the surface's own, then its ancestors'); an undeclared
659
+ * target is refused by name;
660
+ * 2. enforces the mode: `stream` takes ops from the target's `streamOps`; ops on any other target
661
+ * need `patchable` (+ `updatesValue`); a value on a `stream` target is refused;
662
+ * 3. checks the kind (rule 10): a person's mismatch WARNS (the receipt is still applied, with a
663
+ * `warning` and a `fix`); an agent's, applet's or automation's malformed write is REFUSED;
664
+ * 4. applies the policy: manual → a person only; ask → a person's own act is the approval, anyone
665
+ * else asks through `approvals`; queued → filed through `review`; auto → applies;
666
+ * 5. applies through the handler: the mounted page's LIVE handler wins over the HEADLESS one;
667
+ * neither → refused `unapplicable` ("open <surface> to apply it");
668
+ * 6. turns stale / missing record / broken protected span into "cannot apply" with a one-click
669
+ * remedy (rule 11).
670
+ *
671
+ * Every outcome is a `Receipt` carrying the system's own sentence. `write` never throws.
672
+ *
673
+ * Who counts as a person: `person`, `menu` and `destination` (a destination send is a person's own
674
+ * click on "Send to …"). `agent`, `applet` and `automation` are not.
675
+ *
676
+ * Open-risk ruling — stream ops into an entity target: an entity write is ONE atomic save. Ops reach
677
+ * an entity target only when it is declared `patchable` (the ops are handed to the handler in one
678
+ * call and commit as one save); a non-patchable entity target refuses ops with the remedy "stream
679
+ * into the editor, then save". Op-by-op persistence into a record does not exist.
680
+ */
681
+
682
+ /** Who is writing. `menu` and `destination` are a person's own act. */
683
+ type WriteCaller = "person" | "agent" | "applet" | "automation" | "destination" | "menu";
684
+ /** One text op for a `stream` (or `patchable`) target — the WidgetHandle op set. */
685
+ interface WriteOp {
686
+ op: StreamOp;
687
+ /** The text the op inserts or replaces with. */
688
+ text?: string;
689
+ /** What `replace` / `insert_before` / `insert_after` / `patch` anchor on. */
690
+ find?: string;
691
+ }
692
+ interface WriteRequest {
693
+ surfaceName: string;
694
+ /** A write target name; `"<itemType>.<name>"` names an item's target. */
695
+ target: string;
696
+ itemType?: string;
697
+ /** Which item, by its declared identity values. Required for an item target. */
698
+ itemIdentity?: Record<string, string>;
699
+ /** A whole value. Exactly one of `value` / `ops`. */
700
+ value?: unknown;
701
+ /** Text ops (stream / patchable targets). */
702
+ ops?: readonly WriteOp[];
703
+ by: WriteCaller;
704
+ runId?: string;
705
+ }
706
+ /** What a handler receives: the request plus the declared target it resolved to. */
707
+ interface WriteApplyRequest {
708
+ surfaceName: string;
709
+ /** The surface that declares the target (an ancestor when inherited). */
710
+ declaredOn: string;
711
+ target: WriteTarget;
712
+ item?: {
713
+ itemType: string;
714
+ identity: Record<string, string>;
715
+ };
716
+ value?: unknown;
717
+ ops?: readonly WriteOp[];
718
+ by: WriteCaller;
719
+ runId?: string;
720
+ }
721
+ /** Rule 11: the three "cannot apply" signals. */
722
+ type CannotApply = "stale" | "missing-record" | "broken-span";
723
+ /**
724
+ * A handler applies the write. Return nothing (or `{ status: "applied" }`) when it landed, or a
725
+ * `cannotApply` signal; THROWING an error whose `code` is a `CannotApply` signal means the same.
726
+ */
727
+ type WriteHandlerResult = void | {
728
+ status: "applied";
729
+ sentence?: string;
730
+ } | {
731
+ status: "cannot-apply";
732
+ cannotApply: CannotApply;
733
+ sentence?: string;
734
+ remedy?: string;
735
+ };
736
+ type WriteHandler = (request: WriteApplyRequest, signal: AbortSignal) => WriteHandlerResult | Promise<WriteHandlerResult>;
737
+ /** Files a `queued` write for an organization's review. */
738
+ interface WriteReviewPort {
739
+ file(request: WriteApplyRequest): Promise<{
740
+ sentence?: string;
741
+ remedy?: string;
742
+ } | void>;
743
+ }
744
+ /** Why a write was refused. */
745
+ type WriteRefusalReason = "undeclared" | "needs_item" | "malformed" | "declaration_broken" | "manual_only" | "needs_approval" | "declined" | "no_review" | "unapplicable" | "cannot_apply" | "cancelled" | "failed";
746
+ interface WriteDoor {
747
+ write(request: WriteRequest, signal?: AbortSignal): Promise<Receipt>;
748
+ /** A feature's write handler that works with no page mounted. Refuses a second one for the same target. */
749
+ registerHeadless(surfaceName: string, targetName: string, handler: WriteHandler): () => void;
750
+ /** A mounted page's handler; wins over the headless one while registered. Returns unregister. */
751
+ registerLive(surfaceName: string, targetName: string, handler: WriteHandler): () => void;
752
+ }
753
+ /** The declarations the door reads: a `DeclarationRegistry` satisfies it. */
754
+ interface WriteDoorDeclarations {
755
+ get(surfaceName: string): {
756
+ writeTargets?: readonly WriteTarget[];
757
+ itemTypes?: readonly ItemType[];
758
+ } | undefined;
759
+ /** Parent chain, root first (the registry's `ancestry`). Absent = no inheritance. */
760
+ ancestry?(surfaceName: string): string[];
761
+ }
762
+ type WriteDoorPorts = Pick<AlchemyHostPorts, "diagnostics" | "kinds" | "approvals" | "review">;
763
+ declare class DuplicateWriteHandlerError extends Error {
764
+ constructor(surfaceName: string, targetName: string);
765
+ }
766
+ declare function createWriteDoor(options: {
767
+ ports: WriteDoorPorts;
768
+ declarations: WriteDoorDeclarations;
769
+ }): WriteDoor;
770
+
771
+ /**
772
+ * Surface Actions — the shapes (Applets CONTRACTS §6, FROZEN; exported here as a superset).
773
+ *
774
+ * An Action is one thing a surface can have done to it, by a person, an agent,
775
+ * an applet or an automation: a write target, a client tool, a Kind Action or a
776
+ * row in `ui.ui_surface_action`. All of them project onto `ActionDeclaration`
777
+ * (`./declarations.ts`) and run through ONE runner (`./surface-run.ts`). There is
778
+ * never a second registry: `name` IS the alchemy action id, and `category`
779
+ * defaults to "applet" in alchemy's closed `ActionCategory` union.
780
+ *
781
+ * Types only — no runtime code, no React, no `@ai-matrx/agents`. `/ports`
782
+ * imports from here, so this file imports nothing but local types.
783
+ */
784
+
785
+ /** Who started a run. */
786
+ type ActionCaller = "person" | "agent" | "applet" | "automation";
787
+ /** Who may run it without a click: "manual" = only a person; "ask" = proposed first; "auto" = runs. */
788
+ type ActionPolicy = "ask" | "auto" | "manual";
789
+ interface ActionContext {
790
+ runId: string;
791
+ by: ActionCaller;
792
+ viewerId: string | null;
793
+ surfaceName?: string;
794
+ policy?: ActionPolicy;
795
+ }
796
+ /** The system's own sentence, never thrown into a UI. Superset of RecordsError (CONTRACTS §0 `AppletError`). */
797
+ interface ActionError {
798
+ code: string;
799
+ message: string;
800
+ retryable: boolean;
801
+ diagnostic?: string;
802
+ /** Superset: the one-click remedy a write door refusal names. */
803
+ remedy?: string;
804
+ }
805
+ /** CONTRACTS §0 `Result<T>`. */
806
+ type ActionResult<T = unknown> = {
807
+ ok: true;
808
+ data: T;
809
+ } | {
810
+ ok: false;
811
+ error: ActionError;
812
+ };
813
+ /** `POST /actions/run` (aidream) — the request. */
814
+ interface ServerActionRunRequest {
815
+ name: string;
816
+ input: Json$1;
817
+ by: ActionCaller;
818
+ surface_name?: string;
819
+ policy?: ActionPolicy;
820
+ }
821
+ /** `POST /actions/run` (aidream) — the response. */
822
+ interface ServerActionRunResponse {
823
+ status: "applied" | "proposed" | "refused";
824
+ message: string;
825
+ receipts: Json$1[];
826
+ proposal?: Json$1;
827
+ }
828
+ /** A mandate run request: by alias (an Action's `target`) or by key. */
829
+ type MandateRunRequest = ({
830
+ alias: string;
831
+ key?: never;
832
+ } | {
833
+ key: string;
834
+ alias?: never;
835
+ }) & {
836
+ variables: Record<string, Json$1>;
837
+ userInput?: string;
838
+ by: ActionCaller;
839
+ policy: ActionPolicy;
840
+ };
841
+
642
842
  /**
643
843
  * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).
644
844
  *
@@ -657,7 +857,7 @@ interface ClickTarget {
657
857
  * PP-01a `window` (host-rendered windows for a live preparation session)
658
858
  * PP-13a `transferKnobs` (organization default recipes)
659
859
  *
660
- * ALC-17 adds approvals/bodies/receipts.
860
+ * ALC-17 `door` (the one write door), `review` (queued writes)
661
861
  *
662
862
  * ── Absent-port semantics ───────────────────────────────────────────────────
663
863
  *
@@ -687,6 +887,16 @@ interface ClickTarget {
687
887
  * to an overlay carrying the session as data)
688
888
  * transferKnobs absent → no organization default recipe; a person's own
689
889
  * default (persistence) or the package's Full applies
890
+ * serverActions absent → `runs: "server"` Actions refuse with "not available here"
891
+ * mandates absent → `runs: "mandate"` Actions refuse the same way
892
+ * pageActions absent → `runs: "page"` Actions refuse the same way
893
+ * approvals absent → a policy "ask" Action started by an agent, applet or automation is refused
894
+ * ("needs a person's approval"); a person's own click is the approval
895
+ * (`runs: "navigate"` goes through `overlay.navigate`; overlay absent → refused)
896
+ * door absent → write-target Actions dispatch to `pageActions` as before, and
897
+ * `Delivery.send` is refused with a remedy; bound → every such write goes
898
+ * through it and returns its receipt
899
+ * review absent → a write to a `queued` target is refused ("review isn't available here")
690
900
  *
691
901
  * Types only: this entry has no runtime code.
692
902
  */
@@ -832,6 +1042,40 @@ interface AlchemyHostPorts {
832
1042
  window?: WindowPort;
833
1043
  /** Organization default recipes, resolved by the host's Feature Knob ladder (platform → organization). */
834
1044
  transferKnobs?: TransferKnobsPort;
1045
+ /** aidream `POST /actions/run`: a registered server action by name, as the caller, under the apply-policy cascade. */
1046
+ serverActions?: ServerActionPort;
1047
+ /** Runs a mandate by alias or key (the host binds `@ai-matrx/agents`; alchemy never imports it). */
1048
+ mandates?: MandatePort;
1049
+ /** The page's own handlers for `runs: "page"` Actions (in an applet frame: routed as `{ action, input, runId }`). */
1050
+ pageActions?: PageActionPort;
1051
+ /** Asks a person, in place, to approve an `ask` Action that an agent, applet or automation started. */
1052
+ approvals?: ApprovalPort;
1053
+ /** `createWriteDoor(...)`: every write to a declared target lands here and returns a receipt. */
1054
+ door?: WriteDoor;
1055
+ /** Files a write to a `queued` target for an organization's review. */
1056
+ review?: WriteReviewPort;
1057
+ }
1058
+ interface ServerActionPort {
1059
+ run(request: ServerActionRunRequest): Promise<ServerActionRunResponse>;
1060
+ }
1061
+ interface MandatePort {
1062
+ /** Resolves with the run's result (a kind envelope or JSON); rejects with the system's sentence. */
1063
+ run(request: MandateRunRequest): Promise<unknown>;
1064
+ }
1065
+ interface ApprovalRequest {
1066
+ action: string;
1067
+ label: string;
1068
+ description: string;
1069
+ input: Json;
1070
+ by: "agent" | "applet" | "automation";
1071
+ surfaceName: string;
1072
+ }
1073
+ interface ApprovalPort {
1074
+ /** Resolves true when the person approves; false when they decline or dismiss. */
1075
+ ask(request: ApprovalRequest): Promise<boolean>;
1076
+ }
1077
+ interface PageActionPort {
1078
+ dispatch(name: string, input: unknown, context: ActionContext): Promise<ActionResult<unknown>>;
835
1079
  }
836
1080
  /**
837
1081
  * Why a port and not `OverlayHostPort`: an overlay's `data` is `Json`, and a live preparation
@@ -964,7 +1208,7 @@ type Notice = {
964
1208
  sentence: string;
965
1209
  remedy: string;
966
1210
  };
967
- /** A reference to a declared write target (the write door arrives in ALC-17). */
1211
+ /** A reference to a declared write target (resolved by the one write door, ALC-17). */
968
1212
  interface WriteTargetRef {
969
1213
  surfaceName?: string;
970
1214
  target: string;
@@ -983,7 +1227,7 @@ type TransferOperation = {
983
1227
  } | {
984
1228
  kind: "transform";
985
1229
  transform: string;
986
- options?: Json$1;
1230
+ options?: Json$2;
987
1231
  } | {
988
1232
  kind: "prepare-for-ai";
989
1233
  instruction?: string;
@@ -1028,7 +1272,7 @@ interface ServerOperation {
1028
1272
  statement: string;
1029
1273
  supports(payload: Payload): boolean;
1030
1274
  /** Projected draft only; sensitivity already applied. */
1031
- toInput(draft: Draft): Json$1;
1275
+ toInput(draft: Draft): Json$2;
1032
1276
  }
1033
1277
  /** Delivery results: `copy` and `download` only ever deliver, degrade, cancel or fail (CONTRACT R16). */
1034
1278
  type DeliveryOutcome = Extract<TransferOutcome, {
@@ -1039,11 +1283,17 @@ declare const sealed: unique symbol;
1039
1283
  type SealedArtifact = Artifact & {
1040
1284
  readonly [sealed]: true;
1041
1285
  };
1042
- /** Every send returns one (the write door's receipt shape, CONTRACT §2.3; the door itself is ALC-17). */
1286
+ /**
1287
+ * Every write returns one (CONTRACT §2.3; the door is `createWriteDoor`, ALC-17). An applied
1288
+ * receipt may carry a `warning` with its `fix` (rule 10: a person's kind mismatch warns, never refuses).
1289
+ * A refusal's `reason` is a `WriteRefusalReason` (`./door`).
1290
+ */
1043
1291
  type Receipt = {
1044
1292
  status: "applied";
1045
1293
  to: WriteTargetRef;
1046
1294
  sentence: string;
1295
+ warning?: string;
1296
+ fix?: string;
1047
1297
  } | {
1048
1298
  status: "queued";
1049
1299
  to: WriteTargetRef;
@@ -1067,7 +1317,7 @@ interface Delivery {
1067
1317
  html?: boolean;
1068
1318
  }): Promise<DeliveryOutcome>;
1069
1319
  download(artifact: SealedArtifact, signal: AbortSignal): Promise<DeliveryOutcome>;
1070
- /** Sends the sealed bytes through the write door (ALC-17). Without a door: refused, with a remedy. */
1320
+ /** Sends the sealed bytes through the write door (`by: "destination"`). Without a door: refused, with a remedy. */
1071
1321
  send(artifact: SealedArtifact, to: WriteTargetRef, via: "destination"): Promise<Receipt>;
1072
1322
  }
1073
1323
 
@@ -1110,7 +1360,7 @@ interface PreparationSession {
1110
1360
  readonly snapshot: Snapshot;
1111
1361
  readonly draft: Draft;
1112
1362
  /** Deterministic transform, AI preparation or any registered transform — bumps draft.revision. */
1113
- transform(id: string, options: Json$1, signal: AbortSignal): Promise<Draft>;
1363
+ transform(id: string, options: Json$2, signal: AbortSignal): Promise<Draft>;
1114
1364
  /** A manual edit. */
1115
1365
  edit(payload: Payload): Draft;
1116
1366
  /** Keep only these sections (ids from the snapshot). */
@@ -1130,19 +1380,13 @@ declare function openPreparation(source: Source | Payload, scope: TransferScope,
1130
1380
  declare function sealDraft(draft: Draft, format: string, options: FormatOptions, signal: AbortSignal, formats?: readonly FormatAdapter[]): Promise<SealedArtifact>;
1131
1381
  /**
1132
1382
  * The one delivery. `transport` defaults to the browser (clipboard + download link); a non-browser
1133
- * host binds its own (`TransportPort`). `send` needs the write door (ALC-17): without one it is
1383
+ * host binds its own (`TransportPort`). `send` goes through the one write door (ALC-17): without one it is
1134
1384
  * refused with a remedy, never faked.
1135
1385
  */
1136
1386
  declare function createDelivery(ports?: {
1137
1387
  transport?: Transport;
1138
- door?: {
1139
- apply(request: {
1140
- to: WriteTargetRef;
1141
- value: unknown;
1142
- origin: "user";
1143
- via: "destination";
1144
- }): Promise<Receipt>;
1145
- };
1388
+ /** The one write door (`createWriteDoor`). Absent → `send` is refused with a remedy. */
1389
+ door?: Pick<WriteDoor, "write">;
1146
1390
  }): Delivery;
1147
1391
 
1148
1392
  /**
@@ -1228,19 +1472,19 @@ declare function patternBelow(pattern: string, pointer: string): boolean;
1228
1472
  /** The path a person reads and copies: `/messages/*\/metadata` → `data.messages[*].metadata`. */
1229
1473
  declare function displayPath(pointer: string, root?: string): string;
1230
1474
  /** Exactly `JSON.stringify(value).length`, computed once per object (large sources stay cheap). */
1231
- declare function jsonSize(value: Json$1): number;
1475
+ declare function jsonSize(value: Json$2): number;
1232
1476
  /** The size a person expects for a node: a string's own length, else its JSON. */
1233
- declare function nodeChars(value: Json$1): number;
1477
+ declare function nodeChars(value: Json$2): number;
1234
1478
  /**
1235
1479
  * The one-line stub that stands in for a node: its header (a string's first line, an object's
1236
1480
  * short scalar members) and its original size.
1237
1481
  */
1238
- declare function stubText(value: Json$1): string;
1482
+ declare function stubText(value: Json$2): string;
1239
1483
  /** Every concrete pointer in `value` a pattern names (for counts, diffs and highlights). */
1240
- declare function concretePointers(value: Json$1, pattern: string): string[];
1484
+ declare function concretePointers(value: Json$2, pattern: string): string[];
1241
1485
  /** Apply exclusions and per-node limits to a JSON value; returns the new value and what changed. */
1242
- declare function applyStructureToJson(value: Json$1, recipe: StructureRecipe, labels?: Readonly<Record<string, string>>): {
1243
- value: Json$1;
1486
+ declare function applyStructureToJson(value: Json$2, recipe: StructureRecipe, labels?: Readonly<Record<string, string>>): {
1487
+ value: Json$2;
1244
1488
  omissions: Omission[];
1245
1489
  };
1246
1490
  /** A JSON (or registered) draft with the person's structure choices applied. */
@@ -1250,7 +1494,7 @@ declare function applyJsonStructure(draft: Draft, recipe: StructureRecipe, label
1250
1494
  * earlier sibling is excluded). Null when the node is excluded or cut; a stubbed ancestor answers
1251
1495
  * with the stub's own pointer.
1252
1496
  */
1253
- declare function outputPointer(value: Json$1, recipe: StructureRecipe, pointer: string): string | null;
1497
+ declare function outputPointer(value: Json$2, recipe: StructureRecipe, pointer: string): string | null;
1254
1498
  declare function isProseSection(section: Section): boolean;
1255
1499
  interface SectionLayout {
1256
1500
  text: string;
@@ -1321,4 +1565,4 @@ declare function setPersonDefaultRecipe(ports: Pick<AlchemyHostPorts, "persisten
1321
1565
  [key: string]: Json;
1322
1566
  } | null): Promise<void>;
1323
1567
 
1324
- export { type AgentPayloadEnvironment, type AgentPayloadInput, type AiPreparation, type Artifact, type BoundAllMatching, type BuiltInFormatId, type CapturedAllMatching, type CapturedSource, type Column, ContentTransferError, type Coverage, type Delivery, type DeliveryOutcome, type Draft, EMPTY_STRUCTURE, type ExportPage, type ExportProjection, FORMAT_ADAPTERS, type FormatAdapter, type FormatEngine, type FormatOptions, type Json$1 as Json, type NodeLimit, type NormalizeTransferJsonOptions, type Notice, type Omission, type OutputSpan, type PageAction, type Payload, type PreparationOptions, type PreparationSession, type QuerySnapshot, type RawSnapshot, type Receipt, type RecipeOrigin, type ResolvedRecipe, type SealedArtifact, type Section, type SectionLayout, type ServerOperation, type Snapshot, type Source, type SpanMap, type StructureRecipe, type SurfaceHandle, TRANSFER_DEFAULT_RECIPE_SETTING, type TransferLimits, type TransferOperation, type TransferOutcome, type TransferPreferenceOverrides, type TransferPreferences, type TransferScope, type TransferSurfaceDeclaration, type TransferTarget, type Transform, type Transport, type WriteTargetRef, agentPayloadWithSpans, applyJsonStructure, applySectionSelection, applySectionStructure, applyStructureToJson, applyTransferLimits, assembleAgentPayload, buildAgentPayload, capture, collectAllMatching, concretePointers, createBrowserTransport, createDelivery, createDraft, createSurfaceTransferHandle, deriveDraft, directSource, displayPath, editDraft, eligibleFormats, exportedColumns, extensionForLanguage, fenceJsonBlock, formatAdapter, isProseSection, isSealed, joinPointer, jsonSize, jsonTextSpans, nodeChars, normalizeTransferJson, offsetSpans, openPreparation, outputPointer, patternBelow, patternCovers, patternMatches, pointerSegments, projectSnapshot, readTransferCell, recipeKey, reduceJson, refreshDraft, resetDraft, resolveDefaultRecipe, resolveTransferPreferences, resolveTransferRegistry, sealArtifact, sealDraft, sealTransferArtifact, sectionLayout, serialize, setPersonDefaultRecipe, sourceChanged, spanMap, stubText, transformRows, undoDraft };
1568
+ export { type AgentPayloadEnvironment, type AgentPayloadInput, type AiPreparation, type Artifact, type BoundAllMatching, type BuiltInFormatId, type CannotApply, type CapturedAllMatching, type CapturedSource, type Column, ContentTransferError, type Coverage, type Delivery, type DeliveryOutcome, type Draft, DuplicateWriteHandlerError, EMPTY_STRUCTURE, type ExportPage, type ExportProjection, FORMAT_ADAPTERS, type FormatAdapter, type FormatEngine, type FormatOptions, type Json$2 as Json, type NodeLimit, type NormalizeTransferJsonOptions, type Notice, type Omission, type OutputSpan, type PageAction, type Payload, type PreparationOptions, type PreparationSession, type QuerySnapshot, type RawSnapshot, type Receipt, type RecipeOrigin, type ResolvedRecipe, type SealedArtifact, type Section, type SectionLayout, type ServerOperation, type Snapshot, type Source, type SpanMap, type StructureRecipe, type SurfaceHandle, TRANSFER_DEFAULT_RECIPE_SETTING, type TransferLimits, type TransferOperation, type TransferOutcome, type TransferPreferenceOverrides, type TransferPreferences, type TransferScope, type TransferSurfaceDeclaration, type TransferTarget, type Transform, type Transport, type WriteApplyRequest, type WriteCaller, type WriteDoor, type WriteDoorDeclarations, type WriteDoorPorts, type WriteHandler, type WriteHandlerResult, type WriteOp, type WriteRefusalReason, type WriteRequest, type WriteReviewPort, type WriteTargetRef, agentPayloadWithSpans, applyJsonStructure, applySectionSelection, applySectionStructure, applyStructureToJson, applyTransferLimits, assembleAgentPayload, buildAgentPayload, capture, collectAllMatching, concretePointers, createBrowserTransport, createDelivery, createDraft, createSurfaceTransferHandle, createWriteDoor, deriveDraft, directSource, displayPath, editDraft, eligibleFormats, exportedColumns, extensionForLanguage, fenceJsonBlock, formatAdapter, isProseSection, isSealed, joinPointer, jsonSize, jsonTextSpans, nodeChars, normalizeTransferJson, offsetSpans, openPreparation, outputPointer, patternBelow, patternCovers, patternMatches, pointerSegments, projectSnapshot, readTransferCell, recipeKey, reduceJson, refreshDraft, resetDraft, resolveDefaultRecipe, resolveTransferPreferences, resolveTransferRegistry, sealArtifact, sealDraft, sealTransferArtifact, sectionLayout, serialize, setPersonDefaultRecipe, sourceChanged, spanMap, stubText, transformRows, undoDraft };