@ai-matrx/alchemy 0.3.6 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.5.0 — 2026-09-25
+
+Adds the `/ports` entry (Matrx Alchemy ALC-13): the host port types for the ALC-13/14 waves only — `kinds` (`KindValidatorPort`, content-ir's validator injected), `diagnostics` (required), `identity` and `persistence` — gathered in `AlchemyHostPorts`, plus `Json`. Types only; no runtime code. Every optional port that a host leaves unbound means its capability is absent, never stubbed. `SchemaSourcePort` is not declared here: it is defined and exported by `@ai-matrx/content-ir/registry`.
+
+### Consumer action
+
+None required. A host that mounts Alchemy may bind `AlchemyHostPorts` once at its boundary; later waves add further optional ports.
+
+## 0.4.0 — 2026-09-25
+
+Alchemy now sits below `@ai-matrx/agents` (ALC-12). The `/matrx` and `/matrx/react` entries, which only re-exported `@ai-matrx/agents/content-transfer[/react]`, are removed, and `@ai-matrx/agents` is no longer a dependency.
+
+### Consumer action
+
+Import `MatrxContentTransferProvider` and the other Matrx adapter symbols from `@ai-matrx/agents/content-transfer/react` and `@ai-matrx/agents/content-transfer` instead of `@ai-matrx/alchemy/matrx/react` and `@ai-matrx/alchemy/matrx`. The `.`, `/core`, `/react`, CSS and SVG entries are unchanged.
+
 ## 0.3.6
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/README.md

@@ -1,6 +1,6 @@
 # @ai-matrx/alchemy
 
-Alchemy is Matrx’s content-to-AI toolkit. **Alchemy Menu** is its small, reusable copy, preparation and export control. This distribution ships the shared core, React controls, Matrx service adapter, CSS and SVG; it contains no parallel implementation.
+Alchemy is Matrx’s content-to-AI toolkit. **Alchemy Menu** is its small, reusable copy, preparation and export control. This distribution ships the shared core, React controls, CSS and SVG; it contains no parallel implementation. It sits below `@ai-matrx/agents` and never depends on it.
 
 ## One menu, ready to use
 
@@ -65,9 +65,7 @@ A provider `email` port enables CSV, JSON and Markdown email actions. The packag
 
 ## Integrate Matrx services once
 
-`MatrxContentTransferProvider` from `@ai-matrx/alchemy/matrx/react` accepts the canonical transport, authenticated database read port, current organization getter and source application. It supplies the declared durable AI preparation job to descendant menus. The host supplies identity and its existing live-run renderer; the package owns preparation, cancellation, exact request recovery and provenance. Mount the provider at an identity boundary so changing user or organization cannot reuse another identity’s prepared run.
-
-The `/matrx` entry also ships `createMatrxTransferPorts(bindings)` and `createMatrxTransferActions(ports)`. Bind existing Notes, Documents, Workbooks, task, attachment, Code and chat openers once. Register the returned actions through the provider's `capabilities.actions`. Menus inherit Save to Matrx and Continue with AI groups; no page callback or styling is necessary. `createMatrxTransferActions` also accepts a partial port set for hosts that expose fewer destinations. The package owns serialization, capture identity checks, saved-item receipts and retry deduplication.
+The Matrx service adapter lives in `@ai-matrx/agents`, which sits above Alchemy. Import `MatrxContentTransferProvider` from `@ai-matrx/agents/content-transfer/react`, and `createMatrxTransferPorts(bindings)` / `createMatrxTransferActions(ports)` from `@ai-matrx/agents/content-transfer`. The provider accepts the canonical transport, authenticated database read port, current organization getter and source application, and supplies the declared durable AI preparation job to descendant Alchemy menus. Mount it at an identity boundary so changing user or organization cannot reuse another identity’s prepared run. Bind existing Notes, Documents, Workbooks, task, attachment, Code and chat openers once and register the returned actions through the provider's `capabilities.actions`; menus inherit Save to Matrx and Continue with AI groups.
 
 Openers report that an editor was opened, not that the item was saved. Save-and-attach preserves the created note if the destination picker fails. New-chat/window handoffs attach captured content as a text resource, leave the human composer empty and never auto-run. Connected tools are selected through the existing assistant Chat Options picker; this is not an automatic MCP invocation.
 
@@ -89,9 +87,8 @@ const artifact = serialize(createDraft(snapshot), "plain");
 |---|---|
 | `/core` (also package root) | Capture, projection, preparation, serializers, artifacts and transport. |
 | `/react` | `AlchemyMenu`, lower-level `ContentTransferMenu`, surface/provider bindings and React glyph. |
-| `/matrx` | Durable AI preparation and the standard Matrx destination catalog/workflow. |
-| `/matrx/react` | React bindings for that adapter. |
+| `/ports` | Host port types only (`AlchemyHostPorts`, `KindValidatorPort`, `DiagnosticsPort`, `IdentityPort`, `PersistencePort`). A host binds them once at its boundary; an unbound optional port means that capability is absent, never stubbed. |
 | `/styles.css` | Self-contained menu and workspace styling. |
 | `/alchemy.svg`, `/portal.svg`, `/copy-transform.svg` | Packaged icon assets; Portal is default. |
 
-The registry installation canary requires the sibling kit, design-system and agents releases first. Stylesheets import the canonical design-system styling; SVG assets are copied from their one source at build time.
+The registry installation canary requires the sibling kit and design-system releases first, and fails if installing Alchemy pulls in `@ai-matrx/agents`. Stylesheets import the canonical design-system styling; SVG assets are copied from their one source at build time.

package/dist/{matrx.cjs → ports.cjs}

@@ -11,11 +11,9 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/matrx.ts
-var matrx_exports = {};
-module.exports = __toCommonJS(matrx_exports);
-__reExport(matrx_exports, require("@ai-matrx/agents/content-transfer"), module.exports);
-//# sourceMappingURL=matrx.cjs.map
+// src/ports.ts
+var ports_exports = {};
+module.exports = __toCommonJS(ports_exports);
+//# sourceMappingURL=ports.cjs.map

package/dist/ports.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ports.ts"],"sourcesContent":["/**\n * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).\n *\n * The app binds these ONCE, at its boundary (where the Alchemy host is\n * mounted). The package never imports the host.\n *\n * ── Ports arrive with the wave that needs them (chair ruling N8) ────────────\n *\n * This entry declares only the ports the current waves use:\n *\n *   ALC-13  `kinds` (content-ir's validator, injected), `diagnostics` (required)\n *   ALC-14  `identity`, `persistence`\n *\n * Later waves add store/notify/overlay/icons/knobs/i18n/auth/dialogs (ALC-15),\n * transport/assets/server (ALC-16) and approvals/bodies/receipts (ALC-17).\n *\n * ── Absent-port semantics ───────────────────────────────────────────────────\n *\n * Every port except `diagnostics` is OPTIONAL. A port the host does not bind\n * means that capability is ABSENT: the actions, formats or writes that need\n * it are not offered at all. A missing port is never stubbed, never faked\n * with a default that pretends to work, and never shown as a dead control.\n *\n *   kinds        absent → kind validation is absent (no value can be checked,\n *                         so a kind-bearing write is not offered)\n *   diagnostics  REQUIRED → nothing fails silently; contract breaks land here\n *   identity     absent → organization-scoped declarations are absent\n *   persistence  absent → per-person settings are absent (organization and\n *                         platform defaults apply)\n *\n * Types only: this entry has no runtime code.\n */\n\n/** JSON as it crosses a port. */\nexport type Json =\n  | null\n  | boolean\n  | number\n  | string\n  | Json[]\n  | { [key: string]: Json };\n\n/**\n * content-ir's kind validator, injected so Alchemy validates without\n * importing the app or the kind catalog. The host builds it from\n * `@ai-matrx/content-ir`'s `createKindValidator` over its own\n * `SchemaSourcePort` (which content-ir defines and exports; Alchemy never\n * declares it).\n *\n * `unverifiable: true` marks a verdict where the kind could not be checked\n * (not registered, no schema, uncompilable schema, catalog unreachable) — a\n * skip, which is never a pass.\n */\nexport interface KindValidatorPort {\n  validate(\n    kindKey: string,\n    value: unknown,\n    signal: AbortSignal,\n  ): Promise<\n    | { ok: true }\n    | { ok: false; sentence: string; remedy: string; unverifiable?: true }\n  >;\n}\n\n/** Where contract breaks are captured. Required: nothing fails silently. */\nexport interface DiagnosticsPort {\n  capture(\n    error: unknown,\n    context: {\n      area: \"declare\" | \"operate\" | \"write\" | \"actions\" | \"menu\";\n      detail: Json;\n    },\n  ): void;\n}\n\n/** Who is using the app right now, and in which organization. */\nexport interface IdentityPort {\n  /** `null` while the host has no resolved identity yet. */\n  current(): {\n    userId: string;\n    organizationId: string | null;\n    isAuthenticated: boolean;\n    isAdmin: boolean;\n  } | null;\n  /** Called whenever `current()` may answer differently; returns unsubscribe. */\n  onChange(listener: () => void): () => void;\n}\n\n/** Per-person settings (layout, density, transfer preferences), layered by the host's settings system. */\nexport interface PersistencePort {\n  readSetting<T extends Json>(key: string): Promise<T | null>;\n  writeSetting(key: string, value: Json): Promise<void>;\n}\n\n/** The ports a host binds. Optional = absent capability when unbound (see above). */\nexport interface AlchemyHostPorts {\n  // ALC-13\n  kinds?: KindValidatorPort;\n  /** REQUIRED from ALC-13 (the only non-optional port): contract breaks are captured here. */\n  diagnostics: DiagnosticsPort;\n  // ALC-14\n  identity?: IdentityPort;\n  persistence?: PersistencePort;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/ports.d.cts

@@ -0,0 +1,91 @@
+/**
+ * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).
+ *
+ * The app binds these ONCE, at its boundary (where the Alchemy host is
+ * mounted). The package never imports the host.
+ *
+ * ── Ports arrive with the wave that needs them (chair ruling N8) ────────────
+ *
+ * This entry declares only the ports the current waves use:
+ *
+ *   ALC-13  `kinds` (content-ir's validator, injected), `diagnostics` (required)
+ *   ALC-14  `identity`, `persistence`
+ *
+ * Later waves add store/notify/overlay/icons/knobs/i18n/auth/dialogs (ALC-15),
+ * transport/assets/server (ALC-16) and approvals/bodies/receipts (ALC-17).
+ *
+ * ── Absent-port semantics ───────────────────────────────────────────────────
+ *
+ * Every port except `diagnostics` is OPTIONAL. A port the host does not bind
+ * means that capability is ABSENT: the actions, formats or writes that need
+ * it are not offered at all. A missing port is never stubbed, never faked
+ * with a default that pretends to work, and never shown as a dead control.
+ *
+ *   kinds        absent → kind validation is absent (no value can be checked,
+ *                         so a kind-bearing write is not offered)
+ *   diagnostics  REQUIRED → nothing fails silently; contract breaks land here
+ *   identity     absent → organization-scoped declarations are absent
+ *   persistence  absent → per-person settings are absent (organization and
+ *                         platform defaults apply)
+ *
+ * Types only: this entry has no runtime code.
+ */
+/** JSON as it crosses a port. */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * content-ir's kind validator, injected so Alchemy validates without
+ * importing the app or the kind catalog. The host builds it from
+ * `@ai-matrx/content-ir`'s `createKindValidator` over its own
+ * `SchemaSourcePort` (which content-ir defines and exports; Alchemy never
+ * declares it).
+ *
+ * `unverifiable: true` marks a verdict where the kind could not be checked
+ * (not registered, no schema, uncompilable schema, catalog unreachable) — a
+ * skip, which is never a pass.
+ */
+interface KindValidatorPort {
+    validate(kindKey: string, value: unknown, signal: AbortSignal): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        sentence: string;
+        remedy: string;
+        unverifiable?: true;
+    }>;
+}
+/** Where contract breaks are captured. Required: nothing fails silently. */
+interface DiagnosticsPort {
+    capture(error: unknown, context: {
+        area: "declare" | "operate" | "write" | "actions" | "menu";
+        detail: Json;
+    }): void;
+}
+/** Who is using the app right now, and in which organization. */
+interface IdentityPort {
+    /** `null` while the host has no resolved identity yet. */
+    current(): {
+        userId: string;
+        organizationId: string | null;
+        isAuthenticated: boolean;
+        isAdmin: boolean;
+    } | null;
+    /** Called whenever `current()` may answer differently; returns unsubscribe. */
+    onChange(listener: () => void): () => void;
+}
+/** Per-person settings (layout, density, transfer preferences), layered by the host's settings system. */
+interface PersistencePort {
+    readSetting<T extends Json>(key: string): Promise<T | null>;
+    writeSetting(key: string, value: Json): Promise<void>;
+}
+/** The ports a host binds. Optional = absent capability when unbound (see above). */
+interface AlchemyHostPorts {
+    kinds?: KindValidatorPort;
+    /** REQUIRED from ALC-13 (the only non-optional port): contract breaks are captured here. */
+    diagnostics: DiagnosticsPort;
+    identity?: IdentityPort;
+    persistence?: PersistencePort;
+}
+
+export type { AlchemyHostPorts, DiagnosticsPort, IdentityPort, Json, KindValidatorPort, PersistencePort };

package/dist/ports.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).
+ *
+ * The app binds these ONCE, at its boundary (where the Alchemy host is
+ * mounted). The package never imports the host.
+ *
+ * ── Ports arrive with the wave that needs them (chair ruling N8) ────────────
+ *
+ * This entry declares only the ports the current waves use:
+ *
+ *   ALC-13  `kinds` (content-ir's validator, injected), `diagnostics` (required)
+ *   ALC-14  `identity`, `persistence`
+ *
+ * Later waves add store/notify/overlay/icons/knobs/i18n/auth/dialogs (ALC-15),
+ * transport/assets/server (ALC-16) and approvals/bodies/receipts (ALC-17).
+ *
+ * ── Absent-port semantics ───────────────────────────────────────────────────
+ *
+ * Every port except `diagnostics` is OPTIONAL. A port the host does not bind
+ * means that capability is ABSENT: the actions, formats or writes that need
+ * it are not offered at all. A missing port is never stubbed, never faked
+ * with a default that pretends to work, and never shown as a dead control.
+ *
+ *   kinds        absent → kind validation is absent (no value can be checked,
+ *                         so a kind-bearing write is not offered)
+ *   diagnostics  REQUIRED → nothing fails silently; contract breaks land here
+ *   identity     absent → organization-scoped declarations are absent
+ *   persistence  absent → per-person settings are absent (organization and
+ *                         platform defaults apply)
+ *
+ * Types only: this entry has no runtime code.
+ */
+/** JSON as it crosses a port. */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * content-ir's kind validator, injected so Alchemy validates without
+ * importing the app or the kind catalog. The host builds it from
+ * `@ai-matrx/content-ir`'s `createKindValidator` over its own
+ * `SchemaSourcePort` (which content-ir defines and exports; Alchemy never
+ * declares it).
+ *
+ * `unverifiable: true` marks a verdict where the kind could not be checked
+ * (not registered, no schema, uncompilable schema, catalog unreachable) — a
+ * skip, which is never a pass.
+ */
+interface KindValidatorPort {
+    validate(kindKey: string, value: unknown, signal: AbortSignal): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        sentence: string;
+        remedy: string;
+        unverifiable?: true;
+    }>;
+}
+/** Where contract breaks are captured. Required: nothing fails silently. */
+interface DiagnosticsPort {
+    capture(error: unknown, context: {
+        area: "declare" | "operate" | "write" | "actions" | "menu";
+        detail: Json;
+    }): void;
+}
+/** Who is using the app right now, and in which organization. */
+interface IdentityPort {
+    /** `null` while the host has no resolved identity yet. */
+    current(): {
+        userId: string;
+        organizationId: string | null;
+        isAuthenticated: boolean;
+        isAdmin: boolean;
+    } | null;
+    /** Called whenever `current()` may answer differently; returns unsubscribe. */
+    onChange(listener: () => void): () => void;
+}
+/** Per-person settings (layout, density, transfer preferences), layered by the host's settings system. */
+interface PersistencePort {
+    readSetting<T extends Json>(key: string): Promise<T | null>;
+    writeSetting(key: string, value: Json): Promise<void>;
+}
+/** The ports a host binds. Optional = absent capability when unbound (see above). */
+interface AlchemyHostPorts {
+    kinds?: KindValidatorPort;
+    /** REQUIRED from ALC-13 (the only non-optional port): contract breaks are captured here. */
+    diagnostics: DiagnosticsPort;
+    identity?: IdentityPort;
+    persistence?: PersistencePort;
+}
+
+export type { AlchemyHostPorts, DiagnosticsPort, IdentityPort, Json, KindValidatorPort, PersistencePort };

package/dist/ports.js

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

package/dist/ports.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-matrx/alchemy",
-  "version": "0.3.6",
-  "description": "Matrx Alchemy: the complete Matrx copy, prepare-for-AI, and export experience, with framework-neutral core, React menu, glyph, styles and Matrx integration.",
+  "version": "0.5.0",
+  "description": "Matrx Alchemy: the complete Matrx copy, prepare-for-AI, and export experience, with framework-neutral core, React menu, glyph and styles.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -68,24 +68,14 @@
         "default": "./dist/react.cjs"
       }
     },
-    "./matrx": {
+    "./ports": {
       "import": {
-        "types": "./dist/matrx.d.ts",
-        "default": "./dist/matrx.js"
+        "types": "./dist/ports.d.ts",
+        "default": "./dist/ports.js"
       },
       "require": {
-        "types": "./dist/matrx.d.cts",
-        "default": "./dist/matrx.cjs"
-      }
-    },
-    "./matrx/react": {
-      "import": {
-        "types": "./dist/matrx-react.d.ts",
-        "default": "./dist/matrx-react.js"
-      },
-      "require": {
-        "types": "./dist/matrx-react.d.cts",
-        "default": "./dist/matrx-react.cjs"
+        "types": "./dist/ports.d.cts",
+        "default": "./dist/ports.cjs"
       }
     },
     "./styles.css": "./dist/styles.css",
@@ -133,13 +123,12 @@
   ],
   "dependencies": {
     "@ai-matrx/design-system": "latest",
-    "@ai-matrx/kit": "latest",
-    "@ai-matrx/agents": "latest"
+    "@ai-matrx/kit": "latest"
   },
   "scripts": {
     "build": "pnpm clean && tsup && node ./scripts/copy-assets.mjs && node ./scripts/assert-distribution-artifacts.mjs",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "check:package": "pnpm build && node ../scripts/check-exports-agreement.mjs && publint && pnpm verify:tarball",
+    "check:package": "pnpm build && node ../scripts/check-exports-agreement.mjs && node ../scripts/check-alchemy-below-agents.mjs && publint && pnpm verify:tarball",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "verify:tarball": "node ./scripts/verify-tarball.mjs"

package/dist/matrx-react.cjs

@@ -1,23 +0,0 @@
-"use client";
-"use strict";
-"use client";
-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 __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/matrx-react.ts
-var matrx_react_exports = {};
-module.exports = __toCommonJS(matrx_react_exports);
-__reExport(matrx_react_exports, require("@ai-matrx/agents/content-transfer/react"), module.exports);
-//# sourceMappingURL=matrx-react.cjs.map

package/dist/matrx-react.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/matrx-react.ts"],"sourcesContent":["\"use client\";\n\nexport * from \"@ai-matrx/agents/content-transfer/react\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAEA,gCAAc,oDAFd;","names":[]}

package/dist/matrx-react.d.cts

@@ -1 +0,0 @@
-export * from '@ai-matrx/agents/content-transfer/react';

package/dist/matrx-react.d.ts

@@ -1 +0,0 @@
-export * from '@ai-matrx/agents/content-transfer/react';

package/dist/matrx-react.js

@@ -1,6 +0,0 @@
-"use client";
-"use client";
-
-// src/matrx-react.ts
-export * from "@ai-matrx/agents/content-transfer/react";
-//# sourceMappingURL=matrx-react.js.map

package/dist/matrx-react.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/matrx-react.ts"],"sourcesContent":["\"use client\";\n\nexport * from \"@ai-matrx/agents/content-transfer/react\";\n"],"mappings":";;;;AAEA,cAAc;","names":[]}

package/dist/matrx.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/matrx.ts"],"sourcesContent":["export * from \"@ai-matrx/agents/content-transfer\";\n"],"mappings":";;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,8CAAd;","names":[]}

package/dist/matrx.d.cts

@@ -1 +0,0 @@
-export * from '@ai-matrx/agents/content-transfer';

package/dist/matrx.d.ts

@@ -1 +0,0 @@
-export * from '@ai-matrx/agents/content-transfer';

package/dist/matrx.js

@@ -1,3 +0,0 @@
-// src/matrx.ts
-export * from "@ai-matrx/agents/content-transfer";
-//# sourceMappingURL=matrx.js.map

package/dist/matrx.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/matrx.ts"],"sourcesContent":["export * from \"@ai-matrx/agents/content-transfer\";\n"],"mappings":";AAAA,cAAc;","names":[]}