@empressaio/atom-contract

中文文档

1.44.0发布于 2026/11/13TypeScriptES Module近 30 天下载 1.5万

输入的数据底座每个皇太后原子都满足:身份、上下文界面、组成声明和历史锚定。对接Hauska SDK(@hauska-sdk/*;每个产品表面和MCP服务器直接消耗.

文档目录20 节

安装
出版(经营者)
公众表面
四层的合约
呼叫地点的范围
组成
准入政策(可见级别)
历史( A) EventAnchoringService (中文(简体) )
VDA 包装( 今天不开放)
内含引用语法
保留原子类型(ADR-020/ADR-021)
石油和天然气原子类型(ADR-025)
属性推理原子类型(主 WDLL 3.2–3.6)
附加制成模式
显示词汇表(OPS-23 R-6/P-167)
读取合同类型(Calibrated Spine F4 / F6 / K6)
测试公用事业
这个包裹不运送什么
线性
许可证

`@empressaio/atom-contract`

每个皇太后原子的输入数据基底必须满足:, 上下文界面、成分声明和历史锁定. 对接Hauska SDK(@hauska-sdk/*);每个产品表面直接消耗和 MCP 服务器.

这个软件包是 仅限框架它运送合同,运行时间它执行它, 计划的历史层写到测试脚手架消费者包用来证明它们的原子符合要求. 目录原子登记(实际原子类型) - engagement, (中文(简体) ), code-section, (中文(简体) ), jurisdiction-corpus(a) 生活在消费品包中这取决于这个.

皇后商业基底,对等到 @hauska-sdk/* 财务报告和审定财务报表 hauska-engine, (中文(简体) ), 每个 doc repo ADR-018(原子合同下层投放)。这个软件包为零 @hauska-sdk/* 依赖性: MCP 服务器或产品表面可以依赖合同而不继承商业堆栈.

安装

npm install @empressaio/atom-contract
# or
pnpm add @empressaio/atom-contract

要求18.18+和 drizzle-orm (^0.30.0),如果您打算使用 PostgresEventAnchoringService无法支撑历史的原子使用情况 createInMemoryEventService() 从 ./testing 子路径.

出版(经营者)

这个 hauska-sdk npm 账户用途 已分阶段发布 + Windows Hello (passkey 2FA),不是颗粒活字符号. 见 docs/npm-publish-automation.md。。。 .

.\publish-1.4.0.ps1
.\publish-approve-1.4.0.ps1 -StageId <uuid-from-stage-list>

公众表面

import {
  createAtomRegistry,
  defaultScope,
  resolveMode,
  parseInlineReferences,
  serializeInlineReference,
  httpContextSummary,
  resolveComposition,
  PostgresEventAnchoringService,
  wrapForStorage,
  unwrapFromStorage,
  type AccessPolicy,
  type AtomRegistration,
  type AtomMode,
  type AtomReference,
  type ContextSummary,
  type Scope,
  type AtomComposition,
  type EventAnchoringService,
} from "@empressaio/atom-contract";

测试公用设施在一个单独的子路径后面所以生产捆绑从来没有拉他们进来:

import {
  createTestRegistry,
  createInMemoryEventService,
  runAtomContractTests,
} from "@empressaio/atom-contract/testing";

四层的合约

具有一个结构型对象的原子登记册:

const taskAtom: AtomRegistration<"task", ["card", "compact", "expanded"]> = {
  // identity
  entityType: "task",
  domain: "sprint",

  // render-mode contract (type-level)
  supportedModes: ["card", "compact", "expanded"],
  defaultMode: "card",

  // context interface
  contextSummary: async (entityId, scope) => ({
    prose: `Task ${entityId}: ...`,
    typed: { id: entityId },
    keyMetrics: [{ label: "Status", value: "open" }],
    relatedAtoms: [],
    historyProvenance: { latestEventId: "evt-...", latestEventAt: "2026-..." },
    scopeFiltered: false,
  }),

  // composition declaration (multi-child; required field)
  composition: [
    { childEntityType: "blocker", childMode: "compact", dataKey: "blockers" },
  ],
};

const registry = createAtomRegistry();
registry.register(taskAtom);

汇编时间保证:

defaultMode 必须是 supportedModes。错配的默认值无法输入检查.
entityType 是一个字面字符串, 一直缩小到 registry.resolve("task") 所以,消费者看到确切的类型回.
domain 需要并且可以通过 registry.listByDomain(...)。。。 .
composition 需要时间。过 [] 宣布没有孩子.

5个模式作为字面结合: inline, (中文(简体) ), compact, (中文(简体) ), card, (中文(简体) ), expanded, (中文(简体) ), focus. 装订(反应) <AtomShell>,每个模式组件, 焦点存储接线) 在一个单独的软件包中存在这取决于这个.

呼叫地点的范围

contextSummary 总是需要一秒钟 Scope 参数 :

interface Scope {
  audience: "ai" | "user" | "internal";
  requestor?: { kind: "user" | "agent"; id: string };
  asOf?: Date;
  permissions?: ReadonlyArray<string>;
}

不按范围区分的原子忽略它并设定 scopeFiltered: false。测试使用 defaultScope() 帮手.

组成

组成是一个多子的宣示图. 登记册消耗字段: registry.validate() 每个注册的构成边缘并报告未登记的儿童实体类型的任何点. 使用 resolveComposition(parent, parentRef, parentData, registry) 改为将声明变成一个已准备好可供渲染的打字儿童列表迭相会.

靴子时间合同 : 应用程序拖带必须调用 registry.validate() 之后的一次 register() 呼叫已经运行无法在结果为时启动 { ok: false }。登记处确实不重验证每个字的构成 register() (父母可以在儿童面前合法登记)和 resolve() 没有重查查,否则会互相引用只在成分分辨率时表面.

组成边缘可通过设置选择退出存在验证 forwardRef: true。前向边缘被两者跳过 validate() 财务报告和审定财务报表 resolveComposition 在孩子没有注册的情况下母原子可以发送一个声明,将一个孩子命名为后来冲刺而未撞出靴子.

准入政策(可见级别)

原子可能声明为 CDR-017 访问级. 合同未履行执行;下游地表(MCP) list_*,目录 APIs)大门打开这个值.

type AccessPolicy =
  | "public-free"        // unauthenticated public catalog
  | "public-paid"        // catalog-visible, entitlement-gated at fetch
  | "platform-internal"  // platform staff only; never enumerated publicly
  | "tenant-private"     // owning tenant only
  | "tenant-shared";     // explicit cross-tenant share (ADR-017)

球场分两地出现:

AtomRegistration.accessPolicy? ——原子类型默认. 有用的时候整个类型是内部的(例如审计原子).
ContextSummary.accessPolicy? ——每件价值. 让我们多数是公用原子标记内部的个别实例——例如:, a 公众 jurisdiction-corpus 伙伴关系支出目录辖区被标记 "platform-internal" 直至伙伴关系关闭.

分辨率:每方 ContextSummary.accessPolicy 当获胜时 ,否则就回到登记簿上 accessPolicy, (中文(简体) ), 否则将原子视为 "public-free"。快速建设者目录( e)registry.describeForPrompt()使登记正常化值为 "public-free" 当未申报的下游过滤分支没有无名卫士.

历史( A)`EventAnchoringService`(中文(简体) )

每个原子突变流经 EventAnchoringService.appendEvent, (中文(简体) ), 将一行写为 atom_events 页:1 运出 PostgresEventAnchoringService 写一个SHA-256链散货. prevHash 链接每个事件到上一个事件 (entityType, entityId) 成对,产生一对实体散列链.

界面-稳定/执行-演变. 这个 EventAnchoringService 接口是合同。决定性因素 SHA-256的执行将取而代之的是真正的加密锁定(Merkle root + 外部分类账锁定)于后一里程碑不改变消费者界面。标记应当为重审结转 TODO(M2-C): 标记.

主办项目拥有 atom_events 计划(表一栏, (见E/CN.4/Sub.2/2000/L.31)。该图书馆根据商定的表格名称发布原始 SQL 只靠靠着 drizzle-orm是因为 sql 帮助SQL调温器.

VDA 包装( 今天不开放)

wrapForStorage(value) 返回时 { envelope: { version: 1, vdaApplied: false }, payload: value } 财务报告和审定财务报表 unwrapFromStorage(stored) 返回时 stored.payload消费者呼唤这些从今天的写入路径; 不操作变成一个真正的信封 (版本链 + 墓碑语义) 在后面的里程碑上没有消费变化.

内含引用语法

聊天层使用 {{atom|type|id|label}}数字 :

parseInlineReferences("see {{atom|task|t1|Pick HVAC}}");
// -> [
//   { kind: "text", text: "see " },
//   { kind: "atom", reference: { kind: "atom", entityType: "task", entityId: "t1", displayLabel: "Pick HVAC" }, raw: "{{atom|task|t1|Pick HVAC}}" }
// ]

分隔符是 |上一个形状 : 无法代表Spec 51本身包含的实体ID : (例如:. parcel-briefing:{parcelId}:{intentHash}) (中文(简体) ). 旧的形状不再了解析 : 没有双段兼容路径 .

保留原子类型(ADR-020/ADR-021)

私人记录的土地使用仪器船,作为Zod验证的有效载荷页:1 ./encumbrances 子路径(v1.2.0+). 类型是永远 public-free; 计划只接受 tenant-private 财务报告和审定财务报表 tenant-shared。。。 .

import {
  RECORDED_INSTRUMENT_SCHEMA,
  RESTRICTION_CLAUSE_SCHEMA,
  ENCUMBRANCE_RENDER_MODES,
  SAMPLE_RECORDED_INSTRUMENT,
} from "@empressaio/atom-contract/encumbrances";

石油和天然气原子类型(ADR-025)

O&G作为Zod验证有效载荷的可操作性、地上和地上原子船页:1 ./og 子路径 (v1. 7. 0). 覆盖资产脊椎(井,井, 完成、区、地、生产时间序列、设备状况、土地 (矿-租赁、rc-租赁、道、所有权-利息)和收入分配单位。主要义务(核心域中立型) 模块,不 ./og。。。 .

import {
  WELL_SCHEMA,
  MINERAL_LEASE_SCHEMA,
  REVENUE_ALLOCATION_UNIT_SCHEMA,
  SAMPLE_WELL,
  OG_DEFAULT_ACCESS_POLICY,
} from "@empressaio/atom-contract/og";

属性推理原子类型(主 WDLL 3.2–3.6)

Parcel可构建的链式原子飞船 ./property 子路径 (v1.9.0+): (中文(简体) ) parcel-node, (中文(简体) ), zoning-fact, (中文(简体) ), setback-rule, (中文(简体) ), buildable-envelope, (中文(简体) ), parcel-terrain-model, (中文(简体) ), road-node, (中文(简体) ), building-footprint, (中文(简体) ), utility-easement, (中文(简体) ), plat-building-line (1.44.0) (中文(简体) ). 均为数据一级(atomTier: "data"默认为 public-free 登记未申报时的准入政策.

(一-E) 校准在READ(一-E)中的信心: 可能带有 ReasoningReadContract 在写作时声称的快照,包括a 占位符 calibratedConfidence 与 provenance: "asserted"在读取, 校正轴通过校正上方解决——它不是被冻结了不添加一个 labeling x district 相乘场.

import {
  ZONING_FACT_SCHEMA,
  SETBACK_RULE_SCHEMA,
  BUILDABLE_ENVELOPE_SCHEMA,
  HAYS_ZONING_FACT_FIXTURE,
  BEXAR_NULL_ZONING_FACT_FIXTURE,
  HAYS_BUILDABLE_ENVELOPE_FIXTURE,
  type ZoningFactAtomInstance,
  type SetbackRuleAtomInstance,
  type BuildableEnvelopeAtomInstance,
} from "@empressaio/atom-contract/property";

`entityType`	`reasoningKind`	关键字段
`parcel-node`	`observed`	`keyKind`, (中文(简体) ), `geometryStoreRef` 指针(绝不是指环) OR `absence`编号 :`verifiedAbsence`
`zoning-fact`	`observed`	`district` 或 `absence.no-zoning-stamp`
`setback-rule`	`observed`	`front`编号 :`side`编号 :`rear`键入 `sourceCodeAtomRef`, (中文(简体) ), `matchBasis`
`buildable-envelope`	`derived`	`buildable-envelope-inset-v1`,输入参考事实+规则+几何
`parcel-terrain-model`	`derived`	`parcel-terrain-mesh-ifc-v1`,格式化的文物
`road-node`	`observed`	`{fips}:road:{osm_way_id}`中线+假定ROW
`building-footprint`	`observed`	`footprintGeometry` 或 `absence`编号 :`verifiedAbsence`· ; `sourceTier`
`utility-easement`	`observed`	`easementGeometry`, (中文(简体) ), `easementClass`, (中文(简体) ), `public-free` 总是; 可选 `easementKind`, (中文(简体) ), `placement`, (中文(简体) ), `platRef` (1.44.0) (中文(简体) )
`plat-building-line`	`observed`	`lineGeometry`编号 :`offsetDistanceFt`, (中文(简体) ), `appliesTo`, (中文(简体) ), `platRef`, (中文(简体) ), `placement` 或 `absence` (1.44.0) (中文(简体) )

parcel-node 铁路一号锁定其他所有地产铁路钥匙它记录包裹身份和戒指PROVENCE;戒指本身留在 txgio_parcel,则 1 个几何真相框架(地理学法则1). geometryStoreRef 严格指针,所以一个内线环无法解析.

ICC 代码引用版税通过核心生成 ObligationAtomInstance 行——无独立 SourceAttribution 类型.

附加制成模式

`entityType`	目的	建议的渲染模式
`recorded-instrument`	父器; 通过湿 PDF `sourceDocumentCid`	`card`, (中文(简体) ), `compact`, (中文(简体) ), `expanded`
`restriction-clause`	可执行片段;计划审查引用目标	`inline` . `focus` (单位:千美元)默认 `focus`(中文(简体) )
`restriction-corpus`	CC & R 分类包	`card`, (中文(简体) ), `expanded`
`administrative-rule`	未记录的人道主义援助准则`legalWeight: advisory`(中文(简体) )	`inline`, (中文(简体) ), `compact`, (中文(简体) ), `card`, (中文(简体) ), `expanded`
`constraint-resolution`	有效制约(ADR-021)	`card`, (中文(简体) ), `expanded`

发动机 AtomRegistration 公升和摄入量生产者属于 hauska-engine/packages/atoms/ (cc-agent-E); Cortex 第1阶段可在引擎注册着陆前验证这些计划上的上传.

显示词汇表(OPS-23 R-6/P-167)

人肉化显示绳索要求飞船 ./display 子路径(v1.32.0+),因此属性探索器面板,可行性PDF, 和 Smart Site MCP 连接器为同一个原子制作相同的单词从一个地方而不是手印副本。两个模块:

buildable数字 : mapBuildableDisplay 及其类型——可建/可置换卡片、PDF和跨地表协议式词汇。逐字记录从五个字节同 buildable-display-vocab.ts 副本曾经生活在hauska-map和hauska-engine, 被平等锁在一起固定装置.
wire数字 : VOCABULARY, (中文(简体) ), WIRE_DISPOSITION_DISPLAY_TEXT, (中文(简体) ), DERIVED_FIGURES_POLICY – Smart Site MCP 线脚词汇页:1 从遗留设计工具逐字移动 artifacts/smartsite-mcp/src/vocabulary.ts (P-91 v3表),随同从 MCP 服务器导入的九个显示常数拥有 mcp-app.ts,因此这个模块对MCP服务器没有依赖性.

import {
  mapBuildableDisplay,
  type BuildableDisplayInput,
  VOCABULARY,
  WIRE_DISPOSITION_DISPLAY_TEXT,
} from "@empressaio/atom-contract/display";

截止到1.32.0,还没有消费者进口这一次路径和以前的副本仍然存在; 退出(删除副本、等值锁和跳过供应商驱动测试)是同一计划行的后一步骤,上门 P-153 在hauska-map和遗产设计工具中合并.

读取合同类型(Calibrated Spine F4 / F6 / K6)

宽, 三轴信心在读取时返回. 毫无障碍, 未来源的置信是无法表达的: 估计是一个品牌名义类型只能通过 createWidthedConfidence。。。 . 在此软件包中不存储衍生数字 .

import {
  createReadContract,
  createWidthedConfidence,
  READ_CONTRACT_SCHEMA,
  SAMPLE_READ_CONTRACT,
  type ReadContract,
  type CalibrationProvenance,
} from "@empressaio/atom-contract/read-contract";

导出	作用
`WidthedConfidence`	不可分离估计数 + `n` + 键 `intervalWidth` + 来源
`ThreeAxisConfidence`	准确性、源质量和后果轴
`ReadContract`	完全的收看对象每一个表面必须发射
`ModelAttributionStamp`	定金印章(型号,即时,原子集id)
`CalibrationProvenance`	`asserted` \| `backtest` \| `seed` \| `live`

传播到MCP,皮层-api, Cortex,扩展和地图是一种消费者- 侧波2 相撞后 ^1.4.0。。。 .

测试公用事业

消费者包进口合同测试套件以证明注册在一个函数调用中是很好的:

import { describe } from "vitest";
import { runAtomContractTests } from "@empressaio/atom-contract/testing";
import { taskAtom } from "./task.reg";

describe("task atom contract", () => {
  runAtomContractTests(taskAtom, {
    withFixture: { entityId: "t1", setUp: seedTestData },
    alsoRegister: [/* any composition children */],
  });
});

套房声称:

身份存在 entityType 非空无一物,
defaultMode 进入 supportedModes, (中文(简体) ),
contextSummary 返回有效的四层形状 historyProvenance 财务报告和审定财务报表 scopeFiltered, (中文(简体) ),
每一个成分边缘都与 alsoRegister + this, (中文(简体) ),
内含此原子的来回引用.

createInMemoryEventService() 提供内存 EventAnchoringService 用于不需要邮购的单位测试; createTestRegistry(initial) 是一个方便结束 createAtomRegistry()。。。 .

这个包裹不运送什么

目录原子注册. 没有 engagement.atom.ts, (中文(简体) ), code-section.atom.ts等. Catalog 原子生活在消费品包中 (单位:千美元)hauska-engine/packages/atoms/,产品 api 服务器等) 取决于这个。行: 此软件包拥有注册机制和合同; 消费者拥有每个原子实例。。。 .
反应渲染层. 只有类型级的渲染模式合同。这个 <AtomRenderer>, (中文(简体) ), <AtomShell>每模式组件,焦点存储接通了,右侧的状态机器所有船在后来的兄弟软件包.
加密锁定 atom_events。。。 . chainHash 实值今天确定性SHA-256; Merkle root + 外部锚地后来的里程碑.
真正的VDA后卫. wrapForStorage 编号 : unwrapFromStorage 为: 无操作; 真正的信封、版本链和墓碑语义在后来的里程碑中着陆.

线性

此软件包提取工作空间- 私人 @workspace/empressa-atom 住在这里的人 legacy-design-tools/lib/empressa-atom/B. 框架已逐字保存;只有软件包名称和 @workspace/db 测试时间依赖性改变.

许可证

见利能斯.

版本与发布记录

@empressaio/atom-contract 共发布 39 个版本，首次发布于 2026/07/07；过去 12 个月发布了 39 个版本。

版本	发布日期	距今
`1.44.0`latest	2026/11/13	今天
`1.43.0`	2026/11/11	2 天前
`1.42.0`	2026/11/06	7 天前
`1.41.0`	2026/11/06	7 天前
`1.40.0`	2026/11/06	7 天前
`1.39.0`	2026/11/06	7 天前

关于 @empressaio/atom-contract 的常见问题

@empressaio/atom-contract 是什么？

输入的数据底座每个皇太后原子都满足:身份、上下文界面、组成声明和历史锚定。对接Hauska SDK(@hauska-sdk/*;每个产品表面和MCP服务器直接消耗.

如何安装 @empressaio/atom-contract？

在项目目录运行 npm install @empressaio/atom-contract，或使用 pnpm add / yarn add / bun add。

@empressaio/atom-contract 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@empressaio/atom-contract 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@empressaio/atom-contract 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=18.18.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@empressaio/atom-contract 可以商用吗？

@empressaio/atom-contract 使用未声明许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

@empressaio/atom-contract 的下载量有多少？

根据 npm 官方下载统计，@empressaio/atom-contract 在 2026/10/14 – 2026/11/12 这 30 天内被下载 14,973 次，日均约 499 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@empressaio/atom-contract 还在维护吗？

最新版本 1.44.0 发布于 2026/11/13（今天）；至今共发布 39 个版本，其中过去 12 个月发布了 39 个；首次发布于 2026/07/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @empressaio/atom-contract

pnpmpnpm add @empressaio/atom-contract
yarnyarn add @empressaio/atom-contract
bunbun add @empressaio/atom-contract

在你的项目目录中运行此命令。

近 30 天下载

14,973

约 1.5万次日均 499 次

统计周期 2026/10/14 – 2026/11/12
数据来自 npm 官方下载统计，今天更新

最新版本1.44.0发布于今天

开源许可未声明未声明

包体积1.9 MB471 个文件 · 解压后

运行依赖2 个

模块格式ES Module无副作用，可 tree-shake

TypeScript自带类型

Node.js>=18.18.0

发布版本39 个近 12 个月 39 个

首次发布2026/07/074 个月前

元数据更新2026/11/13

每一个软件包背后，
都有分享与创造的人。

@empressaio/atom-contract

@empressaio/atom-contract

安装

出版(经营者)

公众表面

四层的合约

呼叫地点的范围

组成

准入政策(可见级别)

历史( A)EventAnchoringService(中文(简体) )

VDA 包装( 今天不开放)

内含引用语法

保留原子类型(ADR-020/ADR-021)

石油和天然气原子类型(ADR-025)

属性推理原子类型(主 WDLL 3.2–3.6)

附加制成模式

显示词汇表(OPS-23 R-6/P-167)

读取合同类型(Calibrated Spine F4 / F6 / K6)

测试公用事业

这个包裹不运送什么

线性

许可证

版本与发布记录

关于 @empressaio/atom-contract 的常见问题

@empressaio/atom-contract 是什么？

如何安装 @empressaio/atom-contract？

@empressaio/atom-contract 支持 TypeScript 吗？

@empressaio/atom-contract 支持 ESM 还是 CommonJS？

@empressaio/atom-contract 需要什么版本的 Node.js？

@empressaio/atom-contract 可以商用吗？

@empressaio/atom-contract 的下载量有多少？

@empressaio/atom-contract 还在维护吗？

`@empressaio/atom-contract`

历史( A)`EventAnchoringService`(中文(简体) )