@ai-matrx/alchemy 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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.

package/README.md

@@ -87,6 +87,7 @@ 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. |
+| `/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. |
 

package/dist/ports.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/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,6 +1,6 @@
 {
   "name": "@ai-matrx/alchemy",
-  "version": "0.4.0",
+  "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",
@@ -68,6 +68,16 @@
         "default": "./dist/react.cjs"
       }
     },
+    "./ports": {
+      "import": {
+        "types": "./dist/ports.d.ts",
+        "default": "./dist/ports.js"
+      },
+      "require": {
+        "types": "./dist/ports.d.cts",
+        "default": "./dist/ports.cjs"
+      }
+    },
     "./styles.css": "./dist/styles.css",
     "./tap-target.css": "./dist/tap-target.css",
     "./alchemy.svg": "./dist/alchemy.svg",