@godspeedai/cognate-artifacts

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

Durable, addressable, content-hashed artifacts with access policy, retention, and tombstones (spec §13.1).

原始使用文档
文档目录6 节
  1. Installation
  2. Quick start
  3. How it behaves
  4. Limitations
  5. Related packages
  6. License

@godspeedai/cognate-artifacts

Durable, content-addressed, access-controlled file storage for Cognate applications. Artifacts are the supported way for a run to produce or consume binary content — reports, documents, images, data files — that must survive restarts and stay auditable.

When to use this package: your agents or capabilities need to attach files to a run and read them back later, with per-tenant access control, retention metadata, and deletions that leave an explicit tombstone instead of silently vanishing. It stores everything in any @godspeedai/cognate-events DurableStore, so persistence is exactly as durable as your store.

Installation

bun add @godspeedai/cognate-artifacts

Requires Bun >= 1.4.0. You also need a store: @godspeedai/cognate-store-sqlite for durable storage or @godspeedai/cognate-store-memory for tests. The SDK ships Bun-native TypeScript source, so add @types/bun and @types/node as dev dependencies when typechecking your project.

Quick start

import { openSqliteStore } from "@godspeedai/cognate-store-sqlite";
import { ArtifactService } from "@godspeedai/cognate-artifacts";

const store = openSqliteStore({ path: "./app.sqlite" });
const artifacts = new ArtifactService(store);

const alice = { id: "alice", kind: "user" } as const;

const record = await artifacts.put({
  name: "refund-report.md",
  mediaType: "text/markdown",
  bytes: new TextEncoder().encode("# Refund\napproved"),
  access: { tenant: "tenant-a", scopeId: "root", readers: ["alice"] },
  runId: "run-1",
  correlationId: "corr-1",
  retention: { class: "case-7y", until: "2033-01-01T00:00:00Z" },
});

const read = await artifacts.get(record.id, alice, "tenant-a");
if (read.kind === "ok") {
  console.log(record.contentHash); // `sha256:<hex>` of the bytes
  console.log(new TextDecoder().decode(read.bytes));
}

// Only principals in `readers` of the right tenant may read:
await artifacts.get(record.id, { id: "bob", kind: "user" }, "tenant-a"); // { kind: "denied" }

How it behaves

  • Write-ahead bytes. put stores the bytes content-addressed (sha256:<hex>) before committing the record and its artifact.created event, so a record is never visible without its content. Identical bytes are stored once, even across artifacts.
  • Honest reads. get returns a discriminated result: ok, denied (wrong tenant or not on the reader allowlist), not_found, tombstoned (deliberately removed under your retention/privacy policy), or lost (record exists but its bytes are gone — reported distinctly as data loss, never hidden behind a not-found answer).
  • Deletion is a tombstone. delete(id, reason, actor) marks the record tombstoned with who deleted it and why, then deletes byte blobs that no remaining artifact references — shared content survives deletion of any one referencer.
  • Representations. One artifact can carry multiple media types (for example a markdown original plus a JSON table view); get(id, actor, tenant, "application/json") selects one.
  • Listing. list({ tenant, runId? }, actor) returns only records the actor is authorized to read.

Limitations

  • Retention (class and until) is recorded metadata. Nothing in this package schedules or enforces expiry — build that on top with your own job.
  • Access control is a flat reader-id allowlist per artifact plus tenant matching. Roles, groups, and per-scope policies are your application's job.
  • list scans all artifact records; there is no secondary index.
  • Tombstoned records keep their event history in the store. Erasing event payloads is the store's payload-erasure feature, not something this package does.

License

Apache-2.0

版本与发布记录

@godspeedai/cognate-artifacts 共发布 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-artifacts 的常见问题

@godspeedai/cognate-artifacts 是什么?

Durable, addressable, content-hashed artifacts with access policy, retention, and tombstones (spec §13.1).

如何安装 @godspeedai/cognate-artifacts?

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

@godspeedai/cognate-artifacts 支持 TypeScript 吗?

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

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

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

@godspeedai/cognate-artifacts 可以商用吗?

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

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

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

@godspeedai/cognate-artifacts 还在维护吗?

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