@landmark-plugin/contracts

Landmark 宿主、插件 SDK、隔离运行时、CLI 和测试工具共享的公开协议包。该包不依赖宿主源码，提供 JavaScript 运行时实现和完整 TypeScript 声明。

普通插件优先从 @landmark-plugin/sdk/* 导入；只有工具链、运行时或需要直接处理协议的代码才直接依赖本包。

稳定协议

• PLUGIN_API_VERSION：插件能力 API 主版本。
• PLUGIN_SDK_VERSION：SDK 发布版本。
• PLUGIN_RPC_PROTOCOL_VERSION：独立进程通信协议版本。
• PLUGIN_MANIFEST_VERSION：清单格式版本。
• assertApiCompatibility()、assertProtocolCompatibility()：启动前兼容性断言。

可执行 Schema

import { schema } from "@landmark-plugin/contracts";

const input = schema.object({
    id: schema.uuid(),
    email: schema.email(),
    name: schema.string().min(1).max(80),
    page: schema.number().integer().min(1).default(1),
    tags: schema.array(schema.string()).max(20).optional(),
});

const value = input.parse(unknownValue);
const result = input.safeParse(unknownValue);

支持 string、number、integer、boolean、null、unknown、literal、enum、array、record、object、union、email、url 和 uuid；支持 optional、nullable、default、min、max 和 pattern。parse() 失败时抛出带结构化 issues 的 PluginSchemaValidationError，safeParse() 返回判别联合结果。

toJsonSchema() 可生成 JSON Schema，供文档、CLI 和跨语言工具链使用。

插件定义

• defineServerPlugin()：校验 API 版本、setup 和递增的数据迁移版本。
• defineClientPlugin()：校验 API 版本和 setup。
• defineService()：校验服务 ID、方法、输入 Schema 和输出 Schema，并深度冻结定义。
• defineEntity()：校验实体名、字段类型、keyField、索引引用和字段 pattern，并深度冻结定义。

标准响应

response.json/text/empty/redirect/file/download/stream/sse 创建可识别的跨进程响应。响应构造器会校验 HTTP 状态、Header 名称与换行注入、重定向地址、下载文件名和 JSON 可序列化性。

使用 validatePluginResponse()、isPluginResponse() 和 assertPluginResponse() 检查外部响应对象。

标准错误

PluginError 保留 code、HTTP status、details、retryable 和 expose。normalizePluginError() 将任意异常转换成标准错误；serializePluginError() 与 deserializePluginError() 用于跨进程传播，并可控制是否暴露堆栈。

RPC 协议

createRpcEnvelope() 创建并冻结 request、response、event、cancel、stream 和 heartbeat 消息。它按消息类型检查 ID、请求方法、deadline 和错误载荷；validateRpcEnvelope() 返回问题列表，assertRpcEnvelope() 用于入口强制校验。

Manifest V1

validatePluginManifestV1() 和 assertPluginManifestV1() 检查：

• 身份、语义版本、publisher 和宿主/Node engine。
• process/container 兼容模式与默认模式。
• eager/lazy 后端激活模式与空闲休眠时间。
• RPC 协议版本。
• 内存、CPU、PID、消息大小资源边界。
• startup/request/shutdown/heartbeat 超时边界。
• 重启次数和退避时间。
• 网络声明。
• 后端入口、同源前端入口和样式路径安全。
• uses 唯一性以及 provides 结构。

pluginManifestV1Schema 供编辑器和外部 JSON Schema 工具使用；JavaScript 运行时应以 validatePluginManifestV1() 为最终判定。