@godspeedai/cognate-kernel-cordis

中文文档
0.10.0发布于 2026/11/16Apache-2.0ES Module构建来源已验证近 30 天下载 3542

Cordis-backed implementation of @godspeedai/cognate-kernel-api. The only package allowed to import cordis.

原始使用文档
文档目录6 节
  1. Installation
  2. Quick start
  3. What the engine guarantees
  4. Limitations
  5. Related packages
  6. License

@godspeedai/cognate-kernel-cordis

A complete implementation of the @godspeedai/cognate-kernel-api kernel contract — scopes, components, capabilities, fibers, effects, policy — built on the Cordis plugin system. This is the only Cognate package that imports cordis, and no Cordis type appears in its public surface: consumers program entirely against the kernel contract.

When to use this package: you want a standalone capability kernel without the rest of the runtime. Most applications meet it indirectly through @godspeedai/cognate-runtime-bun, which embeds this kernel.

Installation

bun add @godspeedai/cognate-kernel-cordis

Requires Bun >= 1.4.0 (cordis is installed automatically as a dependency).

Quick start

import { allowCapabilities, isUnavailable } from "@godspeedai/cognate-kernel-api";
import { createCordisKernel } from "@godspeedai/cognate-kernel-cordis";

const kernel = await createCordisKernel({
  tenant: "tenant-a",
  principal: { id: "system", kind: "system" },
  policy: allowCapabilities("allow-greetings", ["greet"]),
});

// Mount a component; its activation runs, and its capability is published on success.
const handle = await kernel.mount({
  id: "greeter",
  provides: [{ id: "greet", version: "1.0.0" }],
  activate(fiber) {
    fiber.effects.register(() => console.log("greeter cleaned up"));
    fiber.provide({ id: "greet", version: "1.0.0" }, async (name: string) => ({ hello: name }));
  },
});
await handle.waitFor("ACTIVE");

// Resolution matches deterministically and never consults policy;
// the invocation is what the policy authorizes.
const resolved = kernel.resolve({ capability: "greet" });
if (!isUnavailable(resolved)) {
  const result = await resolved.invoke("Ada", {
    actor: { id: "alice", kind: "user" },
    correlationId: "corr-1",
  });
  console.log(result); // { ok: true, value: { hello: "Ada" } }
}

// Disposes every fiber and effect, children first.
await kernel.shutdown("done");

createCordisKernel is a KernelFactory: it returns a Kernel whose mount, resolve, observe, and shutdown follow the shared contract. A failed resolution is not an exception — it returns { unavailable: true, requirement, reason }, which isUnavailable distinguishes from a lease.

What the engine guarantees

  • All-or-nothing activation. A failed activation disposes that attempt's effects in reverse order and publishes nothing. A component whose requirements are missing stays WAITING with no fiber and activates automatically when a compatible provider appears.
  • Orderly teardown. handle.dispose, scope.close, and kernel.shutdown run every disposer in reverse order and are idempotent; failures aggregate into a single CleanupError rejection. Closing a scope closes its children first.
  • Cancellation. Every activation and invocation carries an AbortSignal, aborted on caller cancellation, deadline expiry, or provider teardown.
  • Retries with backoff. Transient activation failures retry per the component's retry policy. Throwing PermanentActivationError skips retries until handle.reset(). Activation that exceeds activationTimeoutMs (default 30 seconds) fails transiently instead of hanging.
  • Scoped visibility. A provided capability is visible in its scope and its descendants only; sibling scopes never see it. Child scopes may narrow the principal and never gain authority by inheritance.
  • Audit. kernel.observe streams fiber-state transitions, capability publication and withdrawal, cleanup failures, and every policy decision.

Limitations

  • In-process and single-tenant: one kernel serves one tenant, and there is no network surface. The runtime layers caller tenancy and services on top.
  • Mounting into a closed scope throws ScopeClosedError.
  • The kernel resolves and invokes capabilities but knows nothing about durability, runs, events, or persistence — that is the runtime's job.

License

Apache-2.0

版本与发布记录

@godspeedai/cognate-kernel-cordis 共发布 20 个版本,首次发布于 2026/10/09;过去 12 个月发布了 20 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.10.0latest2026/11/16今天
0.9.22026/11/152 天前
0.9.12026/11/143 天前
0.9.02026/11/0610 天前
0.8.02026/10/2720 天前
0.7.12026/10/2523 天前

关于 @godspeedai/cognate-kernel-cordis 的常见问题

@godspeedai/cognate-kernel-cordis 是什么?

Cordis-backed implementation of @godspeedai/cognate-kernel-api. The only package allowed to import cordis.

如何安装 @godspeedai/cognate-kernel-cordis?

在项目目录运行 npm install @godspeedai/cognate-kernel-cordis,或使用 pnpm add / yarn add / bun add。

@godspeedai/cognate-kernel-cordis 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/godspeedai__cognate-kernel-cordis 是否存在。

@godspeedai/cognate-kernel-cordis 支持 ESM 还是 CommonJS?

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

@godspeedai/cognate-kernel-cordis 可以商用吗?

@godspeedai/cognate-kernel-cordis 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@godspeedai/cognate-kernel-cordis 的下载量有多少?

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

@godspeedai/cognate-kernel-cordis 还在维护吗?

最新版本 0.10.0 发布于 2026/11/16(今天);至今共发布 20 个版本,其中过去 12 个月发布了 20 个;首次发布于 2026/10/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。