@mokuyoaxis/dsh-iris 0.2.7 → 0.3.0-beta.1

package/lib/plugin-operation-store.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { atomicCreatePrivate, atomicWritePrivate } from './private-storage.js';
+import { requestDirectory } from './local-request-root.js';
+import { checkedPluginDependency, pluginFields, pluginJson, pluginFail, pluginObject } from './plugin-contract.js';
+import { inspectCoreArtifactMetadata, findCoreArtifactMetadata } from './core-artifacts.js';
+
+const ID = /^op_[a-f0-9]{64}$/, ARTIFACT = /^artifact_[a-f0-9]{24}$/, UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const STATES = ['queued', 'running', 'succeeded', 'failed', 'canceled', 'interrupted'];
+const CODES = ['dependency_unavailable', 'permission_denied', 'execution_failed'];
+const invalid = () => pluginFail('IRIS_OPERATION_STORE_INVALID', '持久插件 Operation 记录损坏或绑定不一致');
+const hash = value => crypto.createHash('sha256').update(value).digest('hex');
+const canonical = value => Array.isArray(value) ? value.map(canonical) : value !== null && typeof value === 'object'
+  ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+export const pluginInputDigest = (id, input, dependency, sourceArtifactIds = []) => 'sha256:' + hash(JSON.stringify(canonical(['plugin.execute/v1', id, input, checkedPluginDependency(dependency), sourceArtifactIds])));
+const iso = value => typeof value === 'string' && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+const ids = value => Array.isArray(value) && value.length <= 16 && new Set(value).size === value.length && value.every(id => typeof id === 'string' && ARTIFACT.test(id));
+const fileFor = (root, marker, id) => { if (!ID.test(id)) invalid(); return path.join(requestDirectory(root, marker, 'operations'), id + '.json'); };
+const save = (root, marker, record, create = false) => {
+  validatePluginOperation(record, record.id, marker);
+  (create ? atomicCreatePrivate : atomicWritePrivate)(fileFor(root, marker, record.id), JSON.stringify(record) + '\n');
+  return structuredClone(record);
+};
+const now = record => new Date(Math.max(Date.now(), Date.parse(record.updatedAt))).toISOString();
+
+export function validatePluginOperation(record, id, marker) {
+  if (!pluginFields(record, ['schemaVersion', 'id', 'rootId', 'revision', 'action', 'operationId', 'dependency', 'input', 'inputDigest',
+    'sourceArtifactIds', 'reservedArtifactIds', 'ownerInstanceId', 'createdAt', 'updatedAt', 'state', 'cancelRequested', 'startedAt', 'finishedAt', 'result', 'failureCode'],
+  ['schemaVersion', 'id', 'rootId', 'revision', 'action', 'operationId', 'dependency', 'input', 'inputDigest', 'sourceArtifactIds', 'reservedArtifactIds',
+    'ownerInstanceId', 'createdAt', 'updatedAt', 'state', 'cancelRequested']) || record.schemaVersion !== 1 || record.action !== 'plugin.execute'
+      || !ID.test(id) || record.id !== id || record.rootId !== marker.rootId || !Number.isSafeInteger(record.revision) || record.revision < 1
+      || !UUID.test(record.ownerInstanceId) || !STATES.includes(record.state) || !iso(record.createdAt) || !iso(record.updatedAt) || record.updatedAt < record.createdAt
+      || record.cancelRequested !== (record.state === 'canceled') || !ids(record.sourceArtifactIds) || !ids(record.reservedArtifactIds)) invalid();
+  const dependency = checkedPluginDependency(record.dependency);
+  if (dependency.kind !== 'operations' || dependency.contributionId !== record.operationId
+      || !pluginObject(record.input) || record.inputDigest !== pluginInputDigest(record.operationId, record.input, dependency, record.sourceArtifactIds)
+      || Buffer.byteLength(JSON.stringify(record.input)) > 65536) invalid();
+  if (record.reservedArtifactIds.some((value, i) => value !== 'artifact_' + hash(JSON.stringify([record.id, i])).slice(0, 24))) invalid();
+  const active = ['queued', 'running'].includes(record.state), started = Object.hasOwn(record, 'startedAt');
+  if (record.state === 'queued' && (record.revision !== 1 || started || record.reservedArtifactIds.length || record.updatedAt !== record.createdAt)
+      || record.state === 'running' && !started || started && (!iso(record.startedAt) || record.startedAt < record.createdAt || record.startedAt > record.updatedAt)
+      || record.state === 'failed' && !CODES.includes(record.failureCode) || record.state !== 'failed' && Object.hasOwn(record, 'failureCode')) invalid();
+  if (active) { if (Object.hasOwn(record, 'finishedAt') || Object.hasOwn(record, 'result')) invalid(); }
+  else if (!iso(record.finishedAt) || record.finishedAt !== record.updatedAt || !pluginFields(record.result, ['value', 'artifactIds'])
+      || !ids(record.result.artifactIds) || record.result.artifactIds.some(value => !record.reservedArtifactIds.includes(value))
+      || record.state === 'succeeded' && (!started || record.result.artifactIds.length !== record.reservedArtifactIds.length)
+      || record.state !== 'succeeded' && record.result.value !== null
+      || Buffer.byteLength(JSON.stringify(record.result.value)) > 128 * 1024) invalid();
+  return record;
+}
+
+export function validatePluginBinding(root, record) {
+  for (const id of record.sourceArtifactIds) inspectCoreArtifactMetadata(root, id);
+  for (const id of record.result?.artifactIds || []) {
+    const artifact = inspectCoreArtifactMetadata(root, id);
+    if (artifact.kind !== 'plugin-image' || artifact.metadata.pluginOperationId !== record.id
+        || JSON.stringify(artifact.relations) !== JSON.stringify(record.sourceArtifactIds.map(artifactId => ({ type: 'derived-from', artifactId })))) invalid();
+  }
+}
+function read(root, marker, id) {
+  const file = fileFor(root, marker, id), stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 256 * 1024) invalid();
+  let record; try { record = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { invalid(); }
+  return validatePluginOperation(record, id, marker);
+}
+export function pluginSourceArtifacts(input, fields) {
+  const result = [...new Set(fields.flatMap(key => input[key] === undefined ? [] : Array.isArray(input[key]) ? input[key] : [input[key]]))];
+  if (!ids(result)) pluginFail('IRIS_PLUGIN_INPUT_INVALID', '业务来源须为最多 16 个有效 Artifact ID');
+  return result;
+}
+export function acceptPluginOperation(root, marker, id, { operationId, input, dependency, ownerInstanceId, sourceArtifactIds }) {
+  for (const artifactId of sourceArtifactIds) inspectCoreArtifactMetadata(root, artifactId);
+  const time = new Date().toISOString();
+  return save(root, marker, { schemaVersion: 1, id, rootId: marker.rootId, revision: 1, action: 'plugin.execute', operationId,
+    dependency: checkedPluginDependency(dependency), input: pluginJson(input), inputDigest: pluginInputDigest(operationId, input, dependency, sourceArtifactIds),
+    sourceArtifactIds, reservedArtifactIds: [], ownerInstanceId, createdAt: time, updatedAt: time, state: 'queued', cancelRequested: false }, true);
+}
+export function reservePluginArtifact(root, marker, id) {
+  const record = read(root, marker, id);
+  if (record.state !== 'running' || record.reservedArtifactIds.length >= 16) pluginFail('IRIS_PLUGIN_OPERATION_DENIED', '当前业务不可导入更多作品');
+  const artifactId = 'artifact_' + hash(JSON.stringify([record.id, record.reservedArtifactIds.length])).slice(0, 24);
+  save(root, marker, { ...record, revision: record.revision + 1, updatedAt: now(record), reservedArtifactIds: [...record.reservedArtifactIds, artifactId] });
+  return artifactId;
+}
+export function transitionPluginOperation(root, marker, value) {
+  const record = read(root, marker, value.id);
+  if (record.revision !== value.expectedRevision) pluginFail('IRIS_OPERATION_REVISION_CONFLICT', 'Operation 已改变');
+  const allowed = record.state === 'queued' ? ['running', 'failed', 'canceled', 'interrupted'] : record.state === 'running' ? STATES.filter(state => !['queued', 'running'].includes(state)) : [];
+  if (!allowed.includes(value.state)) pluginFail('IRIS_OPERATION_TRANSITION_INVALID', '结束业务不重新排队或重放');
+  if (value.state === 'failed' ? !CODES.includes(value.failureCode) : value.failureCode !== undefined) pluginFail('IRIS_OPERATION_INPUT_INVALID', '业务失败类别无效');
+  const time = now(record), terminal = value.state !== 'running';
+  const artifacts = terminal ? record.reservedArtifactIds.filter(id => findCoreArtifactMetadata(root, id)) : [];
+  return save(root, marker, { ...record, revision: record.revision + 1, state: value.state, updatedAt: time, cancelRequested: value.state === 'canceled',
+    ...(terminal ? { finishedAt: time, result: { value: value.state === 'succeeded' ? pluginJson(value.value) : null, artifactIds: artifacts } } : { startedAt: time }),
+    ...(value.failureCode ? { failureCode: value.failureCode } : {}) });
+}
+export function projectPluginOperation(record) {
+  const { schemaVersion: _version, ownerInstanceId: _owner, reservedArtifactIds: _planned, ...value } = record;
+  return { contractVersion: 0, ...structuredClone(value) };
+}

package/lib/plugin-operations.js

@@ -0,0 +1,28 @@
+// Internal Core invocation boundary. No Provider implementations, Zod, module loading or filesystem.
+import { freezePluginValue, pluginJson, pluginFail } from './plugin-contract.js';
+
+const registries = new WeakMap();
+export function registerPluginOperations(registry, state) { registries.set(registry, state); }
+
+/** Reserve across the Core queue; the public registry never exposes an executable handler. */
+export function reservePluginOperation(registry, id, input, allowedOperations, expectedDependency) {
+  const owned = registries.get(registry);
+  if (!owned) pluginFail('IRIS_PLUGIN_INVALID', '需要当前插件注册实例');
+  owned.requireActive();
+  const operation = owned.operations.get(id);
+  if (!operation) pluginFail('IRIS_PLUGIN_CONTRIBUTION_MISSING', '业务贡献未加载');
+  if (!Array.isArray(allowedOperations) || !allowedOperations.includes(id)) pluginFail('IRIS_PLUGIN_OPERATION_DENIED', '业务贡献未获本次 Core 装配授权');
+  const dependency = registry.dependency('operations', id);
+  if (expectedDependency !== undefined) {
+    registry.assertDependency(expectedDependency);
+    if (expectedDependency.kind !== 'operations' || expectedDependency.contributionId !== id) pluginFail('IRIS_PLUGIN_DEPENDENCY_MISMATCH', '不能用其他贡献的持久依赖执行当前业务');
+  }
+  const checked = operation.schema.safeParse(pluginJson(input));
+  if (!checked.success) pluginFail('IRIS_PLUGIN_INPUT_INVALID', '输入不符合 ' + id + ' 的 Schema');
+  let release;
+  const done = new Promise(resolve => { release = () => { owned.active.delete(done); resolve(); }; });
+  owned.active.add(done);
+  return { mode: operation.descriptor.mode, commands: operation.descriptor.commands, artifactInputs: operation.descriptor.artifactInputs || [],
+    input: freezePluginValue(checked.data), dependency, release,
+    async invoke(context) { return { dependency, value: pluginJson(await operation.handler(freezePluginValue(checked.data), context)) }; } };
+}

package/lib/plugin-registry.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { createProviderRegistry } from './provider-extensions.js';
+import { definePlugin, assertPluginCompatibility, checkedPluginDependency, pluginDependency, qualifiedPluginId,
+  pluginFields, pluginJson, pluginFail, comparePluginVersions, PLUGIN_KINDS } from './plugin-contract.js';
+import { registerPluginOperations } from './plugin-operations.js';
+
+const unavailable = () => pluginFail('IRIS_PLUGIN_CLOSED', '插件注册实例正在关闭或已关闭');
+
+/** Manifest validation precedes every activation. Core owns call reservations and cleanup. */
+export async function createPluginRegistry({ plugins, coreVersion }) {
+  if (!Array.isArray(plugins)) pluginFail('IRIS_PLUGIN_INVALID', 'plugins 须为明确的插件数组');
+  comparePluginVersions(coreVersion, coreVersion);
+  const definitions = plugins.map(definePlugin), entries = new Map(), contributionIds = new Set(), operations = new Map(), cleanups = [], active = new Set();
+  for (const definition of definitions) {
+    const { manifest } = definition; assertPluginCompatibility(manifest, coreVersion);
+    if (entries.has(manifest.id)) pluginFail('IRIS_PLUGIN_INVALID', '插件 ID 重复：' + manifest.id);
+    entries.set(manifest.id, definition);
+    for (const kind of PLUGIN_KINDS) for (const contribution of manifest.contributions[kind]) {
+      const key = kind + ':' + qualifiedPluginId(manifest.id, contribution.id);
+      if (contributionIds.has(key)) pluginFail('IRIS_PLUGIN_INVALID', '贡献完整 ID 重复：' + key);
+      contributionIds.add(key);
+    }
+    for (const operation of manifest.contributions.operations) {
+      let schema;
+      try { schema = z.fromJSONSchema(operation.inputSchema); }
+      catch (cause) { throw Object.assign(new Error('插件输入 Schema 无法编译：' + manifest.id + '.' + operation.id, { cause }), { code: 'IRIS_PLUGIN_INVALID' }); }
+      operations.set(qualifiedPluginId(manifest.id, operation.id), { manifest, descriptor: operation, schema });
+    }
+  }
+  let state = 'loading', providers, disposal, cleanupFailed = false;
+
+  function dispose() {
+    if (!disposal) {
+      state = 'closing';
+      const providerDisposal = providers?.dispose();
+      void providerDisposal?.catch(() => {}); // Awaited below after operation reservations drain.
+      disposal = (async () => {
+        await Promise.allSettled([...active]);
+        const errors = [];
+        try { await providerDisposal; } catch (error) { errors.push(error); }
+        for (const cleanup of [...cleanups].reverse()) {
+          try { await cleanup(); } catch (error) { errors.push(error); }
+        }
+        operations.clear(); state = 'closed'; cleanupFailed = errors.length > 0;
+        if (errors.length) throw new AggregateError(errors, '插件释放失败');
+      })();
+    }
+    return disposal;
+  }
+
+  try {
+    const factories = [];
+    for (const { manifest, activate } of definitions) {
+      let activating = true;
+      const context = Object.freeze({ coreVersion, plugin: Object.freeze({ id: manifest.id, version: manifest.version }),
+        onDispose(cleanup) {
+          if (!activating || typeof cleanup !== 'function') pluginFail('IRIS_PLUGIN_LIFECYCLE', '资源释放须在 activate 完成前注册');
+          cleanups.push(cleanup);
+        } });
+      let implementation;
+      try { implementation = await activate(context); } finally { activating = false; }
+      if (!pluginFields(implementation, ['providers', 'operations'], [])) pluginFail('IRIS_PLUGIN_INVALID', 'activate 须返回 Provider/业务实现映射；资源通过 onDispose 释放');
+      for (const kind of ['providers', 'operations']) {
+        const handlers = implementation[kind] === undefined ? {} : implementation[kind];
+        if (!pluginFields(handlers, manifest.contributions[kind].map(item => item.id))) pluginFail('IRIS_PLUGIN_INVALID', '实现必须与声明的 ' + kind + ' 一一对应');
+        if (kind === 'operations') for (const descriptor of manifest.contributions.operations) {
+          if (typeof handlers[descriptor.id] !== 'function') pluginFail('IRIS_PLUGIN_INVALID', '业务操作必须为函数');
+          operations.get(qualifiedPluginId(manifest.id, descriptor.id)).handler = handlers[descriptor.id];
+        }
+        else if (manifest.contributions.providers.length) factories.push(() => ({ contractVersion: 0, id: manifest.id, version: manifest.version,
+          protocols: manifest.contributions.providers.map(descriptor => {
+            const handler = handlers[descriptor.id];
+            if (!pluginFields(handler, ['normalizeEndpoint', 'createAdapter', 'supportsModel', 'supportsImageEdit'], ['normalizeEndpoint', 'createAdapter'])) {
+              pluginFail('IRIS_PLUGIN_INVALID', 'Provider 实现字段无效');
+            }
+            return { ...handler, id: qualifiedPluginId(manifest.id, descriptor.id), label: descriptor.title,
+              capabilities: descriptor.capabilities, configuration: descriptor.configuration,
+              dependency: pluginDependency(manifest, 'providers', descriptor.id) };
+          }) }));
+      }
+    }
+    providers = await createProviderRegistry({ extensions: factories });
+    state = 'active';
+  } catch (error) {
+    try { await dispose(); } catch (cleanup) { throw new AggregateError([error, cleanup], '插件激活与释放均失败'); }
+    throw error;
+  }
+
+  function dependency(kind, id) {
+    const manifest = definitions.map(item => item.manifest).find(item => item.contributions[kind]?.some(value => qualifiedPluginId(item.id, value.id) === id));
+    if (!manifest) pluginFail('IRIS_PLUGIN_CONTRIBUTION_MISSING', '所需插件贡献未加载');
+    return pluginDependency(manifest, kind, manifest.contributions[kind].find(item => qualifiedPluginId(manifest.id, item.id) === id).id);
+  }
+  function assertDependency(value) {
+    const expected = checkedPluginDependency(value), current = dependency(expected.kind, expected.contributionId);
+    if (Object.keys(expected).some(key => expected[key] !== current[key])) pluginFail('IRIS_PLUGIN_DEPENDENCY_MISMATCH', '原任务依赖的插件或贡献版本不一致；请恢复准确版本，不会重新提交');
+    return current;
+  }
+  const registry = Object.freeze({
+    providers,
+    snapshot: () => ({ contractVersion: 0, coreVersion, state, activeCalls: active.size, cleanupFailed,
+      plugins: definitions.map(({ manifest }) => pluginJson(manifest)),
+      contributions: Object.fromEntries(PLUGIN_KINDS.map(kind => [kind, definitions.flatMap(({ manifest }) => manifest.contributions[kind]
+        .map(entry => ({ ...pluginJson(entry), id: qualifiedPluginId(manifest.id, entry.id), dependency: pluginJson(pluginDependency(manifest, kind, entry.id)) })))])) }),
+    dependency, assertDependency, dispose
+  });
+  registerPluginOperations(registry, { operations, active, requireActive: () => { if (state !== 'active') unavailable(); } });
+  return registry;
+}

package/lib/plugin-selection.js

@@ -0,0 +1,15 @@
+import { checkedPluginDependency, pluginFail } from './plugin-contract.js';
+
+/** Saved authority is an exact dependency list, never a live registry expansion. */
+export function checkedPluginSelection(value = []) {
+  if (!Array.isArray(value) || value.length > 16) pluginFail('IRIS_CONNECTION_INPUT_INVALID', '插件业务须为最多 16 项明确依赖');
+  let result;
+  try { result = value.map(checkedPluginDependency); }
+  catch (error) { if (error.code !== 'IRIS_PLUGIN_INVALID') throw error; pluginFail('IRIS_CONNECTION_INPUT_INVALID', '插件业务依赖格式无效'); }
+  if (result.some(item => item.kind !== 'operations') || new Set(result.map(item => item.contributionId)).size !== result.length) pluginFail('IRIS_CONNECTION_INPUT_INVALID', '插件业务依赖重复或类型无效');
+  return result;
+}
+export function hasPluginSelection(values, dependency) {
+  const pin = checkedPluginDependency(dependency);
+  return values.some(value => JSON.stringify(checkedPluginDependency(value)) === JSON.stringify(pin));
+}

package/lib/plugin-source-image.js

@@ -0,0 +1,5 @@
+// Shared source-image limits for the catalog and the plugin command boundary.
+const MEDIA_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp']);
+export function isPluginSourceImage(artifact) {
+  return MEDIA_TYPES.has(artifact.mediaType) && artifact.size <= 8 * 1024 * 1024;
+}

package/lib/plugin-web-assets.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { freezePluginValue, pluginFail, pluginFields } from './plugin-contract.js';
+
+const WEB_KINDS = ['pages', 'settings', 'renderers'];
+const resources = new WeakMap();
+const invalid = message => pluginFail('IRIS_PLUGIN_WEB_INVALID', message);
+
+/** Only explicitly declared entry/styles. Never serve a plugin directory or evaluate browser JS. */
+export function pinPluginWebAssets(definition, file) {
+  const root = path.dirname(file), entries = new Map();
+  let total = 0;
+  for (const kind of WEB_KINDS) for (const item of definition.manifest.contributions[kind]) {
+    const assets = new Map();
+    for (const relative of [item.entry, ...(item.styles || [])]) {
+      const target = fs.realpathSync(path.join(root, relative)), rel = path.relative(root, target), stat = fs.statSync(target);
+      if (!rel || rel.startsWith('..' + path.sep) || path.isAbsolute(rel) || !stat.isFile()) {
+        pluginFail('IRIS_PLUGIN_INVALID', 'Web 入口必须位于插件目录内');
+      }
+      if (stat.size > 8 * 1024 * 1024 || (total += stat.size) > 16 * 1024 * 1024) invalid('插件 Web 资源超过 8 MiB 单文件 / 16 MiB 总量限制');
+      assets.set(relative, { bytes: fs.readFileSync(target), mediaType: relative.endsWith('.css') ? 'text/css; charset=utf-8' : 'text/javascript; charset=utf-8' });
+    }
+    entries.set(kind + ':' + definition.manifest.id + '.' + item.id, assets);
+  }
+  return entries;
+}
+
+export function registerPluginWebAssets(registry, entries) { resources.set(registry, entries); }
+
+/** A Core service opts in to exact contribution IDs. Installing a plugin never opts in. */
+export function createPluginPanelAssembly(registry, selection = {}) {
+  if (!pluginFields(selection, WEB_KINDS, [])) invalid('Panel 组合选择须为 pages/settings/renderers 的明确 ID 列表');
+  const source = registry?.snapshot(), pinned = resources.get(registry), routes = new Map(), manifest = { contractVersion: 0 }, selected = {};
+  if (source && source.state !== 'active') pluginFail('IRIS_PLUGIN_CLOSED', '插件注册实例正在关闭或已关闭');
+  for (const kind of WEB_KINDS) {
+    const ids = selection[kind] ?? [];
+    if (!Array.isArray(ids) || ids.some(id => typeof id !== 'string') || new Set(ids).size !== ids.length) invalid('Panel 选择须为不重复的完整贡献 ID');
+    selected[kind] = [...ids];
+    manifest[kind] = ids.map(id => {
+      const item = source?.contributions[kind].find(value => value.id === id);
+      if (!item) pluginFail('IRIS_PLUGIN_CONTRIBUTION_MISSING', 'Panel 贡献未加载：' + kind + ':' + id);
+      const assets = pinned?.get(kind + ':' + id);
+      if (!assets) pluginFail('IRIS_PLUGIN_WEB_ASSET_MISSING', 'Panel 贡献须经显式文件入口加载并固定资源：' + id);
+      const base = '/plugin-assets/' + item.dependency.pluginId + '/' + item.dependency.pluginVersion + '/' + kind + '/' + id + '/';
+      for (const [name, asset] of assets) routes.set(base + name, asset);
+      return { id, title: item.title, dependency: item.dependency, entry: base + item.entry,
+        styles: (item.styles || []).map(name => base + name), ...(kind === 'renderers' ? { mediaTypes: item.mediaTypes } : {}) };
+    });
+  }
+  const active = () => !registry || registry.snapshot().state === 'active';
+  freezePluginValue(manifest); freezePluginValue(selected);
+  return Object.freeze({ selection: selected, manifest,
+    has: route => active() && routes.has(route), read: async route => active() ? routes.get(route) || null : null });
+}

package/lib/plugins.d.ts

@@ -0,0 +1,307 @@
+/** Experimental v0. Trusted local code; no sandbox, discovery, installation or implicit grant. */
+import type { ProviderCapability, ProviderMethod, ProviderOperations, ProviderConnection, ProviderFactoryContext, ProviderErrorRecord } from './provider-context.js';
+export { PROVIDER_FACTORY_CONTEXT_VERSION } from './provider-context.js';
+export type { ProviderCapability, ProviderMethod, ProviderOperations, ProviderConnection, ProviderFactoryContext, ProviderNetwork,
+  ProviderErrorRecord, ProviderStage, ProviderAcceptance, ProviderErrorCategory, ProviderOperationContext, ProviderSubmitRequest,
+  ProviderSubmissionResult, ProviderRemoteRequest, ProviderPollResult, ProviderCancelResult, ProviderDownloadRequest,
+  ProviderDiscoveryRequest, ProviderDiscoveryResult, ProviderArtifact, ProviderImageInput } from './provider-context.js';
+export class ProviderContractError extends Error {
+  constructor(message: string, details?: Partial<ProviderErrorRecord>);
+  readonly stage: ProviderErrorRecord['stage'];
+  readonly category: ProviderErrorRecord['category'];
+  readonly acceptance: ProviderErrorRecord['acceptance'];
+  readonly retryable: boolean;
+  readonly safeMessage: string;
+  readonly httpStatus?: number;
+  readonly providerCode?: string;
+  /** Optional transient transport hint, read by Core health before error persistence. */
+  retryAfterMs?: number;
+  toJSON(): ProviderErrorRecord;
+}
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | { readonly [key: string]: JsonValue };
+export type PluginKind = 'providers' | 'operations' | 'pages' | 'renderers' | 'settings';
+export const PLUGIN_CONTRACT_VERSION: 0;
+export const PLUGIN_KINDS: readonly PluginKind[];
+export type PluginCoreCommand = 'artifact.inspect' | 'artifact.read' | 'artifact.list' | 'task.inspect' | 'task.list' | 'artifact.import';
+export const PLUGIN_CORE_COMMANDS: Readonly<Record<PluginCoreCommand, 'reader' | 'writer'>>;
+export class PluginContractError extends Error { constructor(code: string, message: string); readonly code: string; }
+export interface PluginDependency {
+  readonly contractVersion: 0;
+  readonly pluginId: string;
+  readonly pluginVersion: string;
+  readonly kind: PluginKind;
+  /** Fully qualified pluginId.localId. */
+  readonly contributionId: string;
+  readonly contributionVersion: string;
+}
+export interface Contribution { readonly id: string; readonly version: string; readonly title: string; }
+export interface ProviderContribution extends Contribution {
+  readonly capabilities: readonly ('image-gen' | 'video-gen' | 'tts' | 'music-gen' | 'transcribe')[];
+  readonly configuration?: readonly { key: 'baseUrl' | 'mediaBaseUrl' | 'apiKey'; label: string; type: 'url' | 'secret'; required?: boolean; advanced?: boolean }[];
+}
+export interface OperationContribution extends Contribution {
+  readonly mode: 'reader' | 'writer';
+  readonly commands: readonly PluginCoreCommand[];
+  /** Top-level string or string-array input fields containing source Artifact IDs. Bound at acceptance. */
+  readonly artifactInputs?: readonly string[];
+  /** Closed root object; supported JSON Schema subset documented in PLUGINS.md. */
+  readonly inputSchema: { readonly type: 'object'; readonly additionalProperties: false; readonly [key: string]: JsonValue };
+}
+export interface PageContribution extends Contribution {
+  /** Plugin-relative bundled JS/MJS module. Explicit entry loader pins it before Panel selection. */
+  readonly entry: string;
+  readonly styles?: readonly string[];
+}
+export interface RendererContribution extends PageContribution { readonly mediaTypes: readonly string[]; }
+export interface SettingsContribution extends PageContribution {}
+export interface PluginPanelSelection {
+  readonly pages?: readonly string[];
+  readonly settings?: readonly string[];
+  readonly renderers?: readonly string[];
+}
+export interface PluginManifest {
+  readonly contractVersion: 0;
+  readonly id: string;
+  readonly version: string;
+  /** SemVer precedence interval, min inclusive/maxExclusive exclusive. Not npm range syntax. */
+  readonly compatibility: { readonly min: string; readonly maxExclusive: string };
+  readonly contributions: {
+    readonly providers?: readonly ProviderContribution[];
+    readonly operations?: readonly OperationContribution[];
+    readonly pages?: readonly PageContribution[];
+    readonly renderers?: readonly RendererContribution[];
+    readonly settings?: readonly SettingsContribution[];
+  };
+}
+export interface PluginOperationContext {
+  readonly signal: AbortSignal;
+  readonly dependency: PluginDependency;
+  readonly core: { execute(command: PluginCoreCommand, input: Record<string, unknown>): Promise<unknown> };
+}
+export type PluginOperation = (input: Readonly<Record<string, JsonValue>>, context: PluginOperationContext) => JsonValue | Promise<JsonValue>;
+export interface ProviderAdapterInput {
+  id: string; protocol: string; capabilities: ProviderCapability[]; contractVersion?: 0;
+  operations: ProviderOperations;
+  unsupported?: Partial<Record<ProviderMethod, string>>;
+  prepareInput?: (...args: any[]) => unknown;
+  unsupportedPreparation?: string;
+  pluginDependency?: PluginDependency;
+}
+export type ProviderAdapter = Readonly<Omit<ProviderAdapterInput, 'contractVersion' | 'capabilities' | 'operations' | 'unsupported'> & {
+  contractVersion: 0;
+  capabilities: readonly ProviderCapability[];
+  operations: Readonly<ProviderOperations>;
+  unsupported: Readonly<Partial<Record<ProviderMethod, { readonly reason: string }>>>;
+}>;
+export function defineProviderAdapter(input: ProviderAdapterInput): ProviderAdapter;
+export function normalizeMediaEndpoint(value: string): string;
+export interface ProviderImplementation {
+  normalizeEndpoint(value: string): string;
+  createAdapter(provider: Readonly<ProviderConnection>, context: Readonly<ProviderFactoryContext>): ProviderAdapter;
+  supportsModel?(input: { provider: Record<string, unknown>; modelId: string; capability: string; checkEndpoint?: boolean }): boolean;
+  supportsImageEdit?(modelId: string): boolean;
+}
+export interface PluginActivationContext {
+  readonly coreVersion: string;
+  readonly plugin: { readonly id: string; readonly version: string };
+  /** Register during activate, including before awaited initialization; reverse order cleanup. */
+  onDispose(cleanup: () => void | Promise<void>): void;
+}
+export interface PluginImplementation {
+  readonly providers?: Readonly<Record<string, ProviderImplementation>>;
+  readonly operations?: Readonly<Record<string, PluginOperation>>;
+}
+export interface CorePlugin {
+  readonly manifest: PluginManifest;
+  activate(context: PluginActivationContext): PluginImplementation | Promise<PluginImplementation>;
+}
+export function definePlugin(definition: CorePlugin): CorePlugin;
+export interface ProviderRegistry {
+  descriptor(id: string): Readonly<Record<string, any>> | undefined;
+  snapshot(): { state: string; protocols: Record<string, any>[]; extensions: { id: string; version: string }[]; activeCalls: number; cleanupFailed: boolean; contractVersion: 0 };
+  createAdapter(id: string, provider: Record<string, any>, options?: Record<string, any>): ProviderAdapter;
+  dispose(): Promise<void>;
+}
+export interface CorePluginRegistry {
+  readonly providers: ProviderRegistry;
+  snapshot(): {
+    contractVersion: 0; coreVersion: string; state: string; activeCalls: number; cleanupFailed: boolean;
+    plugins: PluginManifest[];
+    contributions: {
+      providers: (ProviderContribution & { dependency: PluginDependency })[];
+      operations: (OperationContribution & { dependency: PluginDependency })[];
+      pages: (PageContribution & { dependency: PluginDependency })[];
+      renderers: (RendererContribution & { dependency: PluginDependency })[];
+      settings: (SettingsContribution & { dependency: PluginDependency })[];
+    };
+  };
+  dependency(kind: PluginKind, qualifiedId: string): PluginDependency;
+  assertDependency(dependency: PluginDependency): PluginDependency;
+  dispose(): Promise<void>;
+}
+export function createCorePluginRegistry(options?: { plugins?: CorePlugin[]; coreVersion?: string }): Promise<CorePluginRegistry>;
+export function loadCorePluginRegistry(options?: { entries?: string[]; coreVersion?: string }): Promise<CorePluginRegistry>;
+export type CoreCapabilityScope = 'read' | 'create' | 'execute' | 'stop';
+export type CoreBridgeCapability = 'image-edit' | 'image-generate' | 'tts' | 'transcribe';
+export interface ContributionAccess {
+  readonly local: 'requires-configuration' | 'requires-grant' | 'descriptor-only' | 'unavailable';
+  readonly web: 'via-media-flow' | 'via-operation' | 'not-exposed' | 'durable-operation-required' | 'not-mounted' | 'available-in-panel' | 'unavailable';
+  readonly mcp: 'via-media-flow' | 'requires-selection' | 'not-exposed' | 'durable-operation-required' | 'not-applicable' | 'unavailable';
+}
+export interface CatalogContribution extends Contribution {
+  readonly dependency: PluginDependency;
+  /** Declaration/assembly facts only; never the caller's authorization or service health. */
+  readonly access: ContributionAccess;
+}
+export interface CoreCapabilitySnapshot {
+  readonly contractVersion: 0;
+  readonly state: string;
+  readonly coreVersion?: string;
+  readonly scopeOptions: readonly { readonly id: CoreCapabilityScope; readonly title: string }[];
+  readonly controlTools: readonly string[];
+  readonly groups: readonly {
+    readonly id: CoreBridgeCapability; readonly recipe: string; readonly title: string; readonly label: string; readonly shortTitle: string;
+    readonly media: string; readonly requiresAudio?: boolean; readonly tools: readonly string[];
+  }[];
+  readonly tools: readonly { readonly name: string; readonly scope: CoreCapabilityScope; readonly description: string }[];
+  readonly pluginTools: CoreCapabilitySnapshot['tools'];
+  readonly pluginControlTools: readonly string[];
+  readonly media: readonly { readonly id: string; readonly title: string; readonly note?: string; readonly capabilities: readonly CoreBridgeCapability[] }[];
+  readonly plugins: readonly { readonly id: string; readonly version: string; readonly compatibility: PluginManifest['compatibility'] }[];
+  readonly contributions: {
+    readonly providers: readonly (ProviderContribution & CatalogContribution)[];
+    readonly operations: readonly (OperationContribution & CatalogContribution)[];
+    /** No browser module path is exposed or mounted by discovery. */
+    readonly pages: readonly CatalogContribution[];
+    readonly renderers: readonly (CatalogContribution & { readonly mediaTypes: readonly string[] })[];
+    readonly settings: readonly CatalogContribution[];
+  };
+}
+export interface CoreCapabilityCatalog {
+  snapshot(options?: { audioEnabled?: boolean; videoEnabled?: boolean; panelContributions?: PluginPanelSelection; allowedOperations?: readonly string[] }): CoreCapabilitySnapshot;
+  /** Validate an explicit local selection. Does not invoke, persist a grant or enable MCP/Web. */
+  selectOperations(ids?: readonly string[]): readonly (OperationContribution & CatalogContribution)[];
+}
+export function createCoreCapabilityCatalog(options?: { registry?: CorePluginRegistry }): CoreCapabilityCatalog;
+export interface CorePluginHost {
+  call(id: string, input: Record<string, JsonValue>, options?: { dependency?: PluginDependency; signal?: AbortSignal }): Promise<{ dependency: PluginDependency; value: JsonValue }>;
+  snapshot(): { state: string; queuedWrites: number; activeWrites: number; activeReaders: number; cleanupFailed: boolean };
+  /** Caller disposes the shared registry after every host has closed. */
+  dispose(): Promise<ReturnType<CorePluginHost['snapshot']>>;
+}
+export function createCorePluginHost(options: { dataRoot: string; registry: CorePluginRegistry; allowedOperations?: string[] }): CorePluginHost;
+export interface CorePluginWorkbenchSnapshot {
+  readonly contractVersion: 0;
+  readonly state: string;
+  readonly origin: string | null;
+  /** Media writes remain disabled; optional Provider editing has a separate owner gate. */
+  readonly readOnly: true;
+  readonly activeReads: number;
+  readonly cleanupFailed?: boolean;
+}
+export interface CorePluginWorkbench {
+  start(options?: { port?: number }): Promise<{ readonly origin: string; readonly accessToken: string; readonly loginUrl: string; readonly loginExpiresAt: string }>;
+  snapshot(): CorePluginWorkbenchSnapshot;
+  readonly closed: Promise<CorePluginWorkbenchSnapshot>;
+  dispose(): Promise<CorePluginWorkbenchSnapshot>;
+}
+export interface CorePasswordPluginWorkbench extends Omit<CorePluginWorkbench, 'start'> {
+  start(options?: { port?: number }): Promise<{ readonly origin: string; readonly accessToken: string; readonly loginUrl: string;
+    readonly authentication: { readonly mode: 'password'; readonly configured: boolean; readonly authId: string;
+      readonly rememberDays: 30; readonly minPasswordLength: 8; readonly maxPasswordLength: 128 } }>;
+}
+export interface CorePluginWorkbenchOptions {
+  dataRoot: string; registry?: CorePluginRegistry; panelContributions?: PluginPanelSelection;
+  panelManifestPath?: string; providerConfigPath?: string; allowProviderManagement?: boolean;
+  /** Omitted: no business runner. []: reconcile/read history only. IDs: explicitly enabled durable businesses. */
+  allowedOperations?: string[];
+  /** Explicit private directory outside dataRoot. Enables owner connection management. */
+  connectionStore?: string;
+  /** Enable the standard HTTP /mcp edge. Does not start a second Core. */
+  allowMcp?: boolean;
+  /** Optional persistent browser password/session store, in a private directory outside dataRoot. */
+  workbenchAuth?: { directory: string };
+}
+export function createCorePluginWorkbench(options: CorePluginWorkbenchOptions & { workbenchAuth: { directory: string } }): CorePasswordPluginWorkbench;
+export function createCorePluginWorkbench(options: Omit<CorePluginWorkbenchOptions, 'workbenchAuth'> & { workbenchAuth?: undefined }): CorePluginWorkbench;
+export function createCorePluginWorkbench(options: CorePluginWorkbenchOptions): CorePluginWorkbench | CorePasswordPluginWorkbench;
+export function checkedPluginDependency(value: unknown): PluginDependency;
+export function comparePluginVersions(a: string, b: string): -1 | 0 | 1;
+
+export interface PluginTheme { readonly mode: 'light' | 'dark'; readonly density: string; readonly accent: 'iris'; }
+export interface PluginWebSession {
+  readonly contractVersion: 0;
+  readonly instanceId: string;
+  readonly rootId?: string | null;
+  readonly operations: readonly string[];
+  readonly readOnly: boolean;
+  readonly audio: boolean;
+  readonly video: boolean;
+  readonly providerManagement: boolean;
+  readonly pluginExecution: boolean;
+  readonly pluginOperations: readonly PluginDependency[];
+}
+export interface PluginArtifact { readonly id: string; readonly mediaType: string; readonly label?: string; }
+export interface PluginWebRequestOptions { readonly signal?: AbortSignal; }
+export interface PluginBusinessRequest {
+  readonly key: string;
+  readonly operationId: string;
+  readonly dependency: PluginDependency;
+  readonly input: Readonly<Record<string, JsonValue>>;
+}
+export interface PluginDurableOperation {
+  readonly contractVersion: 0;
+  readonly id: string;
+  readonly rootId: string;
+  readonly action: 'plugin.execute';
+  readonly operationId: string;
+  readonly dependency: PluginDependency;
+  readonly input: Readonly<Record<string, JsonValue>>;
+  readonly inputDigest: string;
+  readonly sourceArtifactIds: readonly string[];
+  readonly revision: number;
+  readonly state: 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled' | 'interrupted';
+  readonly cancelRequested: boolean;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly startedAt?: string;
+  readonly finishedAt?: string;
+  readonly failureCode?: 'dependency_unavailable' | 'permission_denied' | 'execution_failed';
+  readonly result?: { readonly value: JsonValue; readonly artifactIds: readonly string[] };
+}
+export interface PluginWebApi {
+  runs(query?: Readonly<Record<string, string>>, options?: PluginWebRequestOptions): Promise<JsonValue>;
+  run(id: string, options?: PluginWebRequestOptions): Promise<JsonValue>;
+  models(options?: PluginWebRequestOptions): Promise<JsonValue>;
+  audioModels(options?: PluginWebRequestOptions): Promise<JsonValue>;
+  videoModels(options?: PluginWebRequestOptions): Promise<JsonValue>;
+  artifact(artifact: PluginArtifact, options?: PluginWebRequestOptions): Promise<Blob>;
+  /** Only settings mounts in an explicitly enabled owner Provider-management session. */
+  readonly providers?: {
+    read(options?: PluginWebRequestOptions): Promise<JsonValue>;
+    save(input: Record<string, JsonValue>, options?: PluginWebRequestOptions): Promise<JsonValue>;
+  };
+  /** Present only when the service explicitly owns a durable plugin runner. Core checks each request. */
+  readonly pluginOperations?: {
+    catalog(query?: Readonly<Record<string, string>>, options?: PluginWebRequestOptions): Promise<JsonValue>;
+    history(options?: PluginWebRequestOptions): Promise<JsonValue>;
+    execute(input: PluginBusinessRequest, options?: PluginWebRequestOptions): Promise<{ contractVersion: 0; operation: PluginDurableOperation; idempotentReplay: boolean }>;
+    inspect(id: string, options?: PluginWebRequestOptions): Promise<JsonValue>;
+    lookup(key: string, options?: PluginWebRequestOptions): Promise<JsonValue>;
+    stop(id: string, options?: PluginWebRequestOptions): Promise<JsonValue>;
+  };
+}
+/** Same-origin trusted modules; Shadow DOM is a style boundary, not a security sandbox. */
+export interface PluginWebContext<Container = unknown> {
+  readonly container: Container;
+  readonly signal: AbortSignal;
+  readonly dependency: PluginDependency;
+  readonly session: PluginWebSession;
+  readonly api: PluginWebApi;
+  readonly theme: { current(): PluginTheme; subscribe(listener: (theme: PluginTheme) => void): () => void };
+}
+export interface PluginPageModule<Container = unknown> { mount(context: PluginWebContext<Container>): void | (() => void) | Promise<void | (() => void)>; }
+export interface PluginSettingsModule<Container = unknown> extends PluginPageModule<Container> {}
+export interface PluginRendererModule<Container = unknown> {
+  mount(context: PluginWebContext<Container> & { readonly artifact: PluginArtifact }): void | (() => void) | Promise<void | (() => void)>;
+}