@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.
- package/CHANGELOG.md +60 -0
- package/README.md +3 -0
- package/dist/actions.cjs +1 -1
- package/dist/actions.cjs.map +1 -1
- package/dist/actions.d.cts +465 -4
- package/dist/actions.d.ts +465 -4
- package/dist/actions.js +1 -1
- package/dist/actions.js.map +1 -1
- package/dist/checks.cjs +1 -1
- package/dist/checks.cjs.map +1 -1
- package/dist/checks.d.cts +22 -1
- package/dist/checks.d.ts +22 -1
- package/dist/checks.js +2 -2
- package/dist/checks.js.map +1 -1
- package/dist/core.cjs +1 -1
- package/dist/core.cjs.map +1 -1
- package/dist/core.d.cts +283 -39
- package/dist/core.d.ts +283 -39
- package/dist/core.js +2 -2
- package/dist/core.js.map +1 -1
- package/dist/declare.cjs +1 -1
- package/dist/declare.cjs.map +1 -1
- package/dist/declare.d.cts +12 -4
- package/dist/declare.d.ts +12 -4
- package/dist/declare.js +1 -1
- package/dist/declare.js.map +1 -1
- package/dist/index.cjs +1 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +283 -39
- package/dist/index.d.ts +283 -39
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/menu.cjs +1 -1
- package/dist/menu.cjs.map +1 -1
- package/dist/menu.d.cts +262 -3
- package/dist/menu.d.ts +262 -3
- package/dist/menu.js +1 -1
- package/dist/menu.js.map +1 -1
- package/dist/operate-server.d.cts +11 -1
- package/dist/operate-server.d.ts +11 -1
- package/dist/operate.cjs +1 -1
- package/dist/operate.cjs.map +1 -1
- package/dist/operate.d.cts +283 -39
- package/dist/operate.d.ts +283 -39
- package/dist/operate.js +2 -2
- package/dist/operate.js.map +1 -1
- package/dist/ports.cjs.map +1 -1
- package/dist/ports.d.cts +269 -2
- package/dist/ports.d.ts +269 -2
- package/dist/react-bar.cjs +1 -1
- package/dist/react-bar.cjs.map +1 -1
- package/dist/react-bar.d.cts +4 -2
- package/dist/react-bar.d.ts +4 -2
- package/dist/react-bar.js +1 -1
- package/dist/react-bar.js.map +1 -1
- package/dist/react-host.d.cts +262 -3
- package/dist/react-host.d.ts +262 -3
- package/dist/react-menu.cjs +1 -1
- package/dist/react-menu.cjs.map +1 -1
- package/dist/react-menu.d.cts +4 -2
- package/dist/react-menu.d.ts +4 -2
- package/dist/react-menu.js +1 -1
- package/dist/react-menu.js.map +1 -1
- package/dist/react-overflow.cjs +1 -1
- package/dist/react-overflow.cjs.map +1 -1
- package/dist/react-overflow.d.cts +262 -3
- package/dist/react-overflow.d.ts +262 -3
- package/dist/react-overflow.js +1 -1
- package/dist/react-overflow.js.map +1 -1
- package/dist/react-palette.cjs +1 -1
- package/dist/react-palette.cjs.map +1 -1
- package/dist/react-palette.d.cts +4 -2
- package/dist/react-palette.d.ts +4 -2
- package/dist/react-palette.js +1 -1
- package/dist/react-palette.js.map +1 -1
- package/dist/react-selection.cjs +1 -1
- package/dist/react-selection.cjs.map +1 -1
- package/dist/react-selection.d.cts +4 -2
- package/dist/react-selection.d.ts +4 -2
- package/dist/react-selection.js +1 -1
- package/dist/react-selection.js.map +1 -1
- package/dist/react-sheet.cjs +1 -1
- package/dist/react-sheet.cjs.map +1 -1
- package/dist/react-sheet.d.cts +4 -2
- package/dist/react-sheet.d.ts +4 -2
- package/dist/react-sheet.js +1 -1
- package/dist/react-sheet.js.map +1 -1
- package/package.json +1 -1
package/dist/core.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$
|
|
6
|
-
[key: string]: Json$
|
|
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$
|
|
19
|
+
value: Json$2;
|
|
20
20
|
} | {
|
|
21
21
|
kind: "rows";
|
|
22
|
-
rows: Record<string, Json$
|
|
22
|
+
rows: Record<string, Json$2>[];
|
|
23
23
|
columns: Column[];
|
|
24
24
|
} | {
|
|
25
25
|
kind: "registered";
|
|
26
26
|
format: string;
|
|
27
|
-
value: Json$
|
|
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$
|
|
42
|
-
validation?: Json$
|
|
43
|
-
metadata?: Json$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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
|
-
*
|
|
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
|
|
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$
|
|
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$
|
|
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
|
-
/**
|
|
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 (
|
|
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$
|
|
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`
|
|
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
|
-
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
1243
|
-
value: Json$
|
|
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$
|
|
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$
|
|
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 };
|