@ai-matrx/alchemy 0.8.13 → 0.8.17

package/dist/ports.cjs

@@ -1,19 +1,2 @@
-"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);
+"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))!__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:!0}),mod);var ports_exports={};module.exports=__toCommonJS(ports_exports);
 //# sourceMappingURL=ports.cjs.map

package/dist/ports.cjs.map

@@ -1 +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 *   ALC-15  `store`, `notify`, `overlay`, `icons`, `knobs`, `i18n`, `auth`, `dialogs`\n *\n *   ALC-16  `transport`, `assets`, `server`\n *\n * ALC-17 adds approvals/bodies/receipts.\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 *   store        absent → actions that read named host state or run named\n *                         host commands are absent\n *   notify       absent → outcomes are not announced (diagnostics still captures)\n *   overlay      absent → actions that open an overlay or navigate are absent\n *   icons        absent → rows render label-only (a key is never shown as text)\n *   knobs        absent → the platform default layout/density applies\n *   i18n         absent → labels as written\n *   auth         absent → a signed-out person does not see requiresAuth actions\n *                         (sign-in-then-resume is the capability that is missing)\n *   dialogs      absent → actions that need a host dialog are absent\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\nimport type { ClickTarget } from \"./actions/click-target\";\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/** Neutral state access: named reads and named commands. No Redux type or dispatch crosses this line. */\nexport interface StorePort {\n  /** A named, typed read the host registered (\"activeConversationId\", \"organizationName\"). */\n  read<T extends Json>(key: string): T | null;\n  /** A named command the host registered (\"tasks.setPendingSource\"); resolves with its result. */\n  command(name: string, input: Json): Promise<Json | void>;\n  subscribe(key: string, listener: () => void): () => void;\n}\n\nexport interface NotifyPort {\n  success(sentence: string): void;\n  info(sentence: string): void;\n  /** Every failure names its remedy. */\n  error(sentence: string, remedy: string): void;\n}\n\n/** Overlays are dispatched through the host; the menu never renders a modal. */\nexport interface OverlayHostPort {\n  open(overlayId: string, data: Json, instanceId?: string): void;\n  close(overlayId: string, instanceId?: string): void;\n  navigate(href: string): void;\n}\n\n/** Icon key → the host's icon component. The model only ever holds keys. */\nexport interface IconResolverPort {\n  resolve(key: string): unknown /* host component */ | null;\n}\n\nexport type ContextArrangementKnob = \"classic\" | \"tiered\" | \"command\";\nexport type DensityKnob = \"comfortable\" | \"compact\";\n\n/** ORGANIZATION defaults only; every method takes the organization. */\nexport interface MenuKnobsPort {\n  /** Replaces the constant PLACEMENT_LABEL_OVERRIDE. */\n  placementLabel(placement: string, organizationId: string | null): string | null;\n  /** Replaces the constant DEFAULT_PLACEMENT_MODE. */\n  placementMode(placement: string, organizationId: string | null): \"show\" | \"hide\";\n  /** The organization's default layout and density (platform default when null: command / comfortable). */\n  layout(organizationId: string | null): { context: ContextArrangementKnob; density: DensityKnob } | null;\n}\n\n/** Label translation. Absent = labels as written. */\nexport interface I18nPort {\n  t(key: string, fallback: string): string;\n}\n\n/** Sign in, then resume the action the person picked. */\nexport interface AuthResumePort {\n  isSignedIn(): boolean;\n  /** Stash {actionId, target fingerprint} and open sign-in; after sign-in the next matching menu host resumes it. */\n  signInThenResume(pending: { actionId: string; contentFingerprint: string }): void;\n  takePending(contentFingerprint: string): { actionId: string } | null;\n}\n\n/** Per-instance host dialogs (today's RichDocumentActionContextCallbacks). */\nexport interface HostDialogsPort {\n  requestDelete?(target: ClickTarget): void;\n  requestConvert?(target: ClickTarget): void;\n  requestEditHistory?(target: ClickTarget): void;\n  requestFullPrint?(target: ClickTarget): void;\n  requestSaveTable?(table: { headers: string[]; rows: string[][] }): void;\n  requestFlashcard?(answer: string): 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  // ALC-15\n  store?: StorePort;\n  notify?: NotifyPort;\n  overlay?: OverlayHostPort;\n  icons?: IconResolverPort;\n  /** Organization defaults for menu knobs; a person's own choice is layered over them via persistence (N9). */\n  knobs?: MenuKnobsPort;\n  i18n?: I18nPort;\n  auth?: AuthResumePort;\n  dialogs?: HostDialogsPort;\n  // ALC-16\n  /** Clipboard and download for this runtime (the browser default ships in /operate). */\n  transport?: TransportPort;\n  /** Private or signed images → share-safe URLs before HTML is sealed. Absent = images keep their URL. */\n  assets?: AssetResolverPort;\n  /** Present when the host can reach aidream server operations; absent = server formats are not offered. */\n  server?: ServerPort;\n}\n\n// ── ALC-16 ports (Operate) ──────────────────────────────────────────────────\n\n/** A transferable artifact as the transport sees it (structurally `@ai-matrx/alchemy/operate`'s Artifact). */\nexport interface TransportArtifact {\n  format: string;\n  plainText: string;\n  html?: string;\n  file?: { filename: string; mime: string; bytes: Uint8Array };\n}\nexport type TransportOutcome =\n  | { status: \"success\"; delivered: \"clipboard\" | \"download-started\"; mimeTypes: string[] }\n  | { status: \"degraded\"; delivered: \"plain-text\"; reason: string }\n  | { status: \"cancelled\" }\n  | { status: \"error\"; code: string; message: string; retryable: boolean };\n/** Clipboard and download for a non-browser runtime (MV3 service worker, Tauri — CONTRACT R8). */\nexport interface TransportPort {\n  copy(artifact: TransportArtifact, signal: AbortSignal): Promise<TransportOutcome>;\n  download(artifact: TransportArtifact, signal: AbortSignal): Promise<TransportOutcome>;\n}\nexport interface AssetResolverPort {\n  resolve(url: string, signal: AbortSignal): Promise<{ url: string } | null>;\n}\nexport type ServerResult =\n  | { status: \"bytes\"; filename: string; mime: string; bytes: Uint8Array; notices: readonly { code: string; sentence: string; remedy: string }[] }\n  | { status: \"receipt\"; receipt: { status: string; sentence: string; remedy?: string } };\nexport interface ServerPort {\n  call(operationId: string, input: Json, signal: AbortSignal): Promise<ServerResult>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"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 *   ALC-15  `store`, `notify`, `overlay`, `icons`, `knobs`, `i18n`, `auth`, `dialogs`\n *\n *   ALC-16  `transport`, `assets`, `server`\n *\n * ALC-17 adds approvals/bodies/receipts.\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 *   store        absent → actions that read named host state or run named\n *                         host commands are absent\n *   notify       absent → outcomes are not announced (diagnostics still captures)\n *   overlay      absent → actions that open an overlay or navigate are absent\n *   icons        absent → rows render label-only (a key is never shown as text)\n *   knobs        absent → the platform default layout/density applies\n *   i18n         absent → labels as written\n *   auth         absent → a signed-out person does not see requiresAuth actions\n *                         (sign-in-then-resume is the capability that is missing)\n *   dialogs      absent → actions that need a host dialog are absent\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\nimport type { ClickTarget } from \"./actions/click-target\";\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/** Neutral state access: named reads and named commands. No Redux type or dispatch crosses this line. */\nexport interface StorePort {\n  /** A named, typed read the host registered (\"activeConversationId\", \"organizationName\"). */\n  read<T extends Json>(key: string): T | null;\n  /** A named command the host registered (\"tasks.setPendingSource\"); resolves with its result. */\n  command(name: string, input: Json): Promise<Json | void>;\n  subscribe(key: string, listener: () => void): () => void;\n}\n\nexport interface NotifyPort {\n  success(sentence: string): void;\n  info(sentence: string): void;\n  /** Every failure names its remedy. */\n  error(sentence: string, remedy: string): void;\n}\n\n/** Overlays are dispatched through the host; the menu never renders a modal. */\nexport interface OverlayHostPort {\n  open(overlayId: string, data: Json, instanceId?: string): void;\n  close(overlayId: string, instanceId?: string): void;\n  navigate(href: string): void;\n}\n\n/** Icon key → the host's icon component. The model only ever holds keys. */\nexport interface IconResolverPort {\n  resolve(key: string): unknown /* host component */ | null;\n}\n\nexport type ContextArrangementKnob = \"classic\" | \"tiered\" | \"command\";\nexport type DensityKnob = \"comfortable\" | \"compact\";\n\n/** ORGANIZATION defaults only; every method takes the organization. */\nexport interface MenuKnobsPort {\n  /** Replaces the constant PLACEMENT_LABEL_OVERRIDE. */\n  placementLabel(placement: string, organizationId: string | null): string | null;\n  /** Replaces the constant DEFAULT_PLACEMENT_MODE. */\n  placementMode(placement: string, organizationId: string | null): \"show\" | \"hide\";\n  /** The organization's default layout and density (platform default when null: command / comfortable). */\n  layout(organizationId: string | null): { context: ContextArrangementKnob; density: DensityKnob } | null;\n}\n\n/** Label translation. Absent = labels as written. */\nexport interface I18nPort {\n  t(key: string, fallback: string): string;\n}\n\n/** Sign in, then resume the action the person picked. */\nexport interface AuthResumePort {\n  isSignedIn(): boolean;\n  /** Stash {actionId, target fingerprint} and open sign-in; after sign-in the next matching menu host resumes it. */\n  signInThenResume(pending: { actionId: string; contentFingerprint: string }): void;\n  takePending(contentFingerprint: string): { actionId: string } | null;\n}\n\n/** Per-instance host dialogs (today's RichDocumentActionContextCallbacks). */\nexport interface HostDialogsPort {\n  requestDelete?(target: ClickTarget): void;\n  requestConvert?(target: ClickTarget): void;\n  requestEditHistory?(target: ClickTarget): void;\n  requestFullPrint?(target: ClickTarget): void;\n  requestSaveTable?(table: { headers: string[]; rows: string[][] }): void;\n  requestFlashcard?(answer: string): 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  // ALC-15\n  store?: StorePort;\n  notify?: NotifyPort;\n  overlay?: OverlayHostPort;\n  icons?: IconResolverPort;\n  /** Organization defaults for menu knobs; a person's own choice is layered over them via persistence (N9). */\n  knobs?: MenuKnobsPort;\n  i18n?: I18nPort;\n  auth?: AuthResumePort;\n  dialogs?: HostDialogsPort;\n  // ALC-16\n  /** Clipboard and download for this runtime (the browser default ships in /operate). */\n  transport?: TransportPort;\n  /** Private or signed images → share-safe URLs before HTML is sealed. Absent = images keep their URL. */\n  assets?: AssetResolverPort;\n  /** Present when the host can reach aidream server operations; absent = server formats are not offered. */\n  server?: ServerPort;\n}\n\n// ── ALC-16 ports (Operate) ──────────────────────────────────────────────────\n\n/** A transferable artifact as the transport sees it (structurally `@ai-matrx/alchemy/operate`'s Artifact). */\nexport interface TransportArtifact {\n  format: string;\n  plainText: string;\n  html?: string;\n  file?: { filename: string; mime: string; bytes: Uint8Array };\n}\nexport type TransportOutcome =\n  | { status: \"success\"; delivered: \"clipboard\" | \"download-started\"; mimeTypes: string[] }\n  | { status: \"degraded\"; delivered: \"plain-text\"; reason: string }\n  | { status: \"cancelled\" }\n  | { status: \"error\"; code: string; message: string; retryable: boolean };\n/** Clipboard and download for a non-browser runtime (MV3 service worker, Tauri — CONTRACT R8). */\nexport interface TransportPort {\n  copy(artifact: TransportArtifact, signal: AbortSignal): Promise<TransportOutcome>;\n  download(artifact: TransportArtifact, signal: AbortSignal): Promise<TransportOutcome>;\n}\nexport interface AssetResolverPort {\n  resolve(url: string, signal: AbortSignal): Promise<{ url: string } | null>;\n}\nexport type ServerResult =\n  | { status: \"bytes\"; filename: string; mime: string; bytes: Uint8Array; notices: readonly { code: string; sentence: string; remedy: string }[] }\n  | { status: \"receipt\"; receipt: { status: string; sentence: string; remedy?: string } };\nexport interface ServerPort {\n  call(operationId: string, input: Json, signal: AbortSignal): Promise<ServerResult>;\n}\n"],"mappings":"sjBAAA","names":[]}