@ai-matrx/alchemy 0.5.1 → 0.6.0

package/dist/declare/schema.json

@@ -0,0 +1,414 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/@ai-matrx/alchemy/dist/declare/schema.json",
+  "title": "SurfaceDeclaration",
+  "description": "One surface's declaration (Matrx Alchemy CONTRACT §2.1). GENERATED from src/declare/types.ts by scripts/generate-declare-schema.mjs — never edit by hand. Extension slots (agent roles, client tools) are open properties at the root.",
+  "type": "object",
+  "properties": {
+    "surfaceName": {
+      "type": "string"
+    },
+    "client": {
+      "type": "string"
+    },
+    "executionMode": {
+      "type": "string",
+      "enum": [
+        "python-stream",
+        "nextjs-stream",
+        "browser-realtime",
+        "local-runtime"
+      ]
+    },
+    "description": {
+      "type": "string"
+    },
+    "label": {
+      "type": "string"
+    },
+    "readiness": {
+      "type": "string",
+      "enum": [
+        "verified",
+        "partial",
+        "stub"
+      ]
+    },
+    "readinessNote": {
+      "type": "string"
+    },
+    "urlPattern": {
+      "type": "string"
+    },
+    "inheritsFrom": {
+      "type": "string"
+    },
+    "intro": {
+      "type": "string"
+    },
+    "overlayId": {
+      "type": "string"
+    },
+    "values": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/DeclaredValue"
+      }
+    },
+    "groups": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/ValueGroup"
+      }
+    },
+    "writeTargets": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/WriteTarget"
+      }
+    },
+    "itemTypes": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/ItemType"
+      }
+    },
+    "liveSlots": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "selection",
+          "on-demand",
+          "errors",
+          "requests"
+        ]
+      }
+    },
+    "configNamespaces": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/ConfigNamespaceDeclaration"
+      }
+    },
+    "evidenceSources": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/EvidenceSourceDeclaration"
+      }
+    },
+    "skipBaselineValues": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "surfaceName",
+    "client",
+    "executionMode",
+    "description",
+    "label",
+    "readiness",
+    "values"
+  ],
+  "additionalProperties": true,
+  "$defs": {
+    "ConfigNamespaceDeclaration": {
+      "type": "object",
+      "properties": {
+        "namespace": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "namespace",
+        "label",
+        "description"
+      ],
+      "additionalProperties": false
+    },
+    "DeclaredValue": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "valueType": {
+          "type": "string",
+          "enum": [
+            "string",
+            "number",
+            "boolean",
+            "object",
+            "array",
+            "document"
+          ]
+        },
+        "valueKind": {
+          "type": "string"
+        },
+        "alwaysAvailable": {
+          "type": "boolean"
+        },
+        "typicalCharCount": {
+          "type": "number"
+        },
+        "autoContext": {
+          "type": "boolean"
+        },
+        "group": {
+          "type": "string"
+        },
+        "sortOrder": {
+          "type": "number"
+        },
+        "sensitivity": {
+          "type": "object",
+          "properties": {
+            "exportable": {
+              "type": "boolean"
+            },
+            "classification": {
+              "type": "string",
+              "enum": [
+                "ordinary",
+                "secret",
+                "credential"
+              ]
+            },
+            "includedByDefault": {
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": false
+        },
+        "liveSlot": {
+          "type": "string",
+          "enum": [
+            "selection",
+            "on-demand",
+            "errors",
+            "requests"
+          ]
+        },
+        "role": {
+          "type": "string",
+          "enum": [
+            "data",
+            "request"
+          ]
+        }
+      },
+      "required": [
+        "name",
+        "label",
+        "description",
+        "valueType",
+        "alwaysAvailable",
+        "typicalCharCount"
+      ],
+      "additionalProperties": false
+    },
+    "EvidenceSourceDeclaration": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "const": "processed_document"
+        },
+        "idValue": {
+          "type": "string"
+        },
+        "fileIdValue": {
+          "type": "string"
+        },
+        "labelValue": {
+          "type": "string"
+        },
+        "representation": {
+          "type": "string",
+          "enum": [
+            "clean",
+            "raw"
+          ]
+        }
+      },
+      "required": [
+        "kind",
+        "idValue"
+      ],
+      "additionalProperties": false
+    },
+    "ItemType": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "identity": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "levels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "entityType": {
+          "type": "string"
+        },
+        "values": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/DeclaredValue"
+          }
+        },
+        "writeTargets": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/WriteTarget"
+          }
+        }
+      },
+      "required": [
+        "name",
+        "label",
+        "description",
+        "identity",
+        "values"
+      ],
+      "additionalProperties": false
+    },
+    "ValueGroup": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "sortOrder": {
+          "type": "number"
+        },
+        "description": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "key",
+        "label",
+        "sortOrder"
+      ],
+      "additionalProperties": false
+    },
+    "WriteTarget": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "valueType": {
+          "type": "string",
+          "enum": [
+            "string",
+            "number",
+            "boolean",
+            "object",
+            "array",
+            "document"
+          ]
+        },
+        "valueKind": {
+          "type": "string"
+        },
+        "updatesValue": {
+          "type": "string"
+        },
+        "patchable": {
+          "type": "boolean"
+        },
+        "approvalComparison": {
+          "const": "text-replacement"
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "draft",
+            "entity",
+            "ui",
+            "stream"
+          ]
+        },
+        "streamOps": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "replace",
+              "insert_before",
+              "insert_after",
+              "prepend",
+              "append",
+              "patch"
+            ]
+          }
+        },
+        "applyPolicy": {
+          "type": "string",
+          "enum": [
+            "manual",
+            "ask",
+            "auto",
+            "queued"
+          ]
+        },
+        "destination": {
+          "type": "boolean"
+        },
+        "itemType": {
+          "type": "string"
+        },
+        "group": {
+          "type": "string"
+        },
+        "sortOrder": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "name",
+        "label",
+        "description",
+        "valueType",
+        "mode"
+      ],
+      "additionalProperties": false
+    }
+  }
+}

package/dist/declare-host.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/declare-host.ts
+var declare_host_exports = {};
+module.exports = __toCommonJS(declare_host_exports);
+//# sourceMappingURL=declare-host.cjs.map

package/dist/declare-host.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/declare-host.ts"],"sourcesContent":["/** `@ai-matrx/alchemy/declare/host` — host-binding types (CONTRACT §2.6). */\nexport type { InternalResolvedItem, ItemAnchor, MountedSurface } from \"./declare/host\";\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/declare-host.d.cts

@@ -0,0 +1,78 @@
+/**
+ * Matrx Alchemy — Declare types (CONTRACT §2.1).
+ *
+ * A declaration is plain JSON data (chair ruling N2): no functions, no classes,
+ * no React. Runtime behaviour lives in `MountedSurface` (`/declare/host`) and in
+ * handler registrations, never here. Zero React, zero `@ai-matrx/agents`.
+ */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** Live slot payloads (page-capture's shapes, kept). */
+interface LiveValues {
+    selection?: {
+        choices: Record<string, Json>;
+        text: string | null;
+    };
+    "on-demand"?: readonly OnDemandSection[];
+    errors?: readonly string[];
+    requests?: readonly RecentRequest[];
+}
+interface OnDemandSection {
+    id: string;
+    title: string;
+    description?: string;
+    role: "data" | "request";
+    brief?: Json;
+    load(signal: AbortSignal): Promise<Json>;
+}
+interface RecentRequest {
+    method: string;
+    path: string;
+    status: string;
+    httpStatus?: number;
+    durationMs?: number;
+    requestId?: string;
+    client?: string;
+    requestBody?: Json;
+    requestBodyNote?: string;
+    errorSentence?: string;
+    timestamp: number;
+}
+/** RAW-FREE. What leaves the package about a clicked item. */
+interface ResolvedItem {
+    itemType: string;
+    identity: Record<string, string>;
+    level?: string;
+    readOnly: boolean;
+}
+
+/**
+ * `@ai-matrx/alchemy/declare/host` — HOST-BINDING types only (CONTRACT §2.1, §2.6).
+ * Never imported by providers (`/declare`, `/actions`, `/menu`, `/operate` see only
+ * the raw-free `ResolvedItem`). Types only: no runtime code.
+ */
+
+interface ItemAnchor {
+    /** The host element the person clicked. */
+    element: unknown;
+    level?: string;
+}
+/** Raw item reads: consumed only by projection and the write handler that owns the target. */
+interface InternalResolvedItem extends ResolvedItem {
+    readValues(signal: AbortSignal): Promise<Record<string, unknown>>;
+}
+/** A mounted instance of a declared surface. Structural handle, never a global name lookup. */
+interface MountedSurface {
+    instanceId: string;
+    surfaceName: string;
+    isMounted(): boolean;
+    /** Same revision before and after a read, or capture refuses with "surface-changed". */
+    getRevision?(): string;
+    unsavedChanges?(): boolean;
+    readValues(signal: AbortSignal): Promise<Record<string, unknown>>;
+    readLive?(signal: AbortSignal): Promise<LiveValues>;
+    resolveItem?(anchor: ItemAnchor): InternalResolvedItem | null;
+}
+
+export type { InternalResolvedItem, ItemAnchor, MountedSurface };

package/dist/declare-host.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Matrx Alchemy — Declare types (CONTRACT §2.1).
+ *
+ * A declaration is plain JSON data (chair ruling N2): no functions, no classes,
+ * no React. Runtime behaviour lives in `MountedSurface` (`/declare/host`) and in
+ * handler registrations, never here. Zero React, zero `@ai-matrx/agents`.
+ */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** Live slot payloads (page-capture's shapes, kept). */
+interface LiveValues {
+    selection?: {
+        choices: Record<string, Json>;
+        text: string | null;
+    };
+    "on-demand"?: readonly OnDemandSection[];
+    errors?: readonly string[];
+    requests?: readonly RecentRequest[];
+}
+interface OnDemandSection {
+    id: string;
+    title: string;
+    description?: string;
+    role: "data" | "request";
+    brief?: Json;
+    load(signal: AbortSignal): Promise<Json>;
+}
+interface RecentRequest {
+    method: string;
+    path: string;
+    status: string;
+    httpStatus?: number;
+    durationMs?: number;
+    requestId?: string;
+    client?: string;
+    requestBody?: Json;
+    requestBodyNote?: string;
+    errorSentence?: string;
+    timestamp: number;
+}
+/** RAW-FREE. What leaves the package about a clicked item. */
+interface ResolvedItem {
+    itemType: string;
+    identity: Record<string, string>;
+    level?: string;
+    readOnly: boolean;
+}
+
+/**
+ * `@ai-matrx/alchemy/declare/host` — HOST-BINDING types only (CONTRACT §2.1, §2.6).
+ * Never imported by providers (`/declare`, `/actions`, `/menu`, `/operate` see only
+ * the raw-free `ResolvedItem`). Types only: no runtime code.
+ */
+
+interface ItemAnchor {
+    /** The host element the person clicked. */
+    element: unknown;
+    level?: string;
+}
+/** Raw item reads: consumed only by projection and the write handler that owns the target. */
+interface InternalResolvedItem extends ResolvedItem {
+    readValues(signal: AbortSignal): Promise<Record<string, unknown>>;
+}
+/** A mounted instance of a declared surface. Structural handle, never a global name lookup. */
+interface MountedSurface {
+    instanceId: string;
+    surfaceName: string;
+    isMounted(): boolean;
+    /** Same revision before and after a read, or capture refuses with "surface-changed". */
+    getRevision?(): string;
+    unsavedChanges?(): boolean;
+    readValues(signal: AbortSignal): Promise<Record<string, unknown>>;
+    readLive?(signal: AbortSignal): Promise<LiveValues>;
+    resolveItem?(anchor: ItemAnchor): InternalResolvedItem | null;
+}
+
+export type { InternalResolvedItem, ItemAnchor, MountedSurface };

package/dist/declare-host.js

@@ -0,0 +1 @@
+//# sourceMappingURL=declare-host.js.map

package/dist/declare-host.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}