@godspeedai/cognate-kernel-api 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -12
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,14 +1,90 @@
|
|
|
1
1
|
# @godspeedai/cognate-kernel-api
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
3
|
+
The framework-owned kernel contract for Cognate: components, scopes, capabilities, fibers, effects, and policy — as TypeScript types plus a few deterministic helpers. No engine code ships here.
|
|
4
|
+
|
|
5
|
+
**When to use this package:** you are authoring capability components or writing code that must type against the kernel, or you are implementing a kernel engine. Applications normally get it transitively through
|
|
6
|
+
[`@godspeedai/cognate-runtime-bun`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-bun) or the [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) umbrella.
|
|
7
|
+
|
|
8
|
+
## Installation
|
|
9
|
+
|
|
10
|
+
```sh
|
|
11
|
+
bun add @godspeedai/cognate-kernel-api
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Requires [Bun](https://bun.sh) >= 1.4.0.
|
|
15
|
+
|
|
16
|
+
## What's in the box
|
|
17
|
+
|
|
18
|
+
- **Types** — `Kernel`, `Scope`, `Component`, `FiberContext`, `CapabilityLease`, `Effects`, `Policy`, `InvocationResult`, and the rest of the kernel vocabulary.
|
|
19
|
+
- **`isCompatible(requirement, contract)`** — deterministic capability eligibility: same capability id, same major version with minor/patch >= required, and every required attribute equal. No engine required.
|
|
20
|
+
- **Policies** — `denyAll` (nothing is authorized unless you say so), `rulePolicy(policyId, rules)` (first matching rule decides, no match denies), and `allowCapabilities(policyId, ids)` for explicit allow-lists.
|
|
21
|
+
- **`isUnavailable(value)`** — type guard distinguishing a failed resolution from a lease.
|
|
22
|
+
- **Typed errors** — `CleanupError`, `PermanentActivationError`, `ActivationTimeoutError`, `UndeclaredCapabilityError`, `ScopeClosedError`.
|
|
23
|
+
|
|
24
|
+
## Quick start
|
|
25
|
+
|
|
26
|
+
Declare a component that provides a capability, and pick a policy for its invocations:
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { allowCapabilities, isCompatible } from "@godspeedai/cognate-kernel-api";
|
|
30
|
+
import type { Component } from "@godspeedai/cognate-kernel-api";
|
|
31
|
+
|
|
32
|
+
const greeter: Component = {
|
|
33
|
+
id: "greeter",
|
|
34
|
+
provides: [{ id: "greet", version: "1.0.0" }],
|
|
35
|
+
activate(fiber) {
|
|
36
|
+
// Reversible effects, torn down in reverse order on disposal.
|
|
37
|
+
fiber.effects.register(() => console.log("greeter cleaned up"));
|
|
38
|
+
// Publish the capability; visible only after activation succeeds.
|
|
39
|
+
fiber.provide({ id: "greet", version: "1.0.0" }, async (name: string) => ({
|
|
40
|
+
hello: name,
|
|
41
|
+
}));
|
|
42
|
+
},
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
// Deterministic eligibility — computed locally, no engine involved:
|
|
46
|
+
isCompatible({ capability: "greet", version: "1.0.0" }, greeter.provides![0]!); // true
|
|
47
|
+
|
|
48
|
+
// Every invocation passes through a policy; anything not allowed is denied.
|
|
49
|
+
const policy = allowCapabilities("allow-greetings", ["greet"]);
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Mounting components, resolving leases, and invoking capabilities need an engine: use
|
|
53
|
+
[`@godspeedai/cognate-kernel-cordis`](https://www.npmjs.com/package/@godspeedai/cognate-kernel-cordis)
|
|
54
|
+
or the runtime, which embed one.
|
|
55
|
+
|
|
56
|
+
## Semantics the contract pins down
|
|
57
|
+
|
|
58
|
+
- Resolution never consults policy; every invocation does, and the default is deny. Each decision is emitted as an `invocation` audit event through `kernel.observe`.
|
|
59
|
+
- Invocation never throws: it returns an `InvocationResult` with a typed failure — `unavailable`, `denied`, `deadline_exceeded`, `cancelled`, or `failed`.
|
|
60
|
+
- Activation is all-or-nothing: a failed activation disposes that attempt's effects in reverse order and publishes nothing.
|
|
61
|
+
- Disposal is idempotent, runs every disposer in reverse order, and rejects once with `CleanupError` if any disposer failed.
|
|
62
|
+
- A provided capability is visible in its scope and its descendants only; a child scope may narrow its principal but never gains authority by inheritance.
|
|
63
|
+
|
|
64
|
+
## Conformance kit for engine implementers
|
|
65
|
+
|
|
66
|
+
If you implement `KernelFactory`, run the executable contract unchanged in your own test suite:
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
import { contractSuite } from "@godspeedai/cognate-kernel-api/conformance";
|
|
70
|
+
import { createCordisKernel } from "@godspeedai/cognate-kernel-cordis";
|
|
71
|
+
|
|
72
|
+
contractSuite("my-kernel", createCordisKernel);
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The subpath exports six suites (`contractSuite`, `lifecycleSuite`, `effectsSuite`, `dependenciesSuite`, `scopesSuite`, `authoritySuite`) plus a `fixtures` namespace with ready-made principals, providers, and consumers for your own kernel tests.
|
|
76
|
+
|
|
77
|
+
## Limitations
|
|
78
|
+
|
|
79
|
+
- This package enforces nothing at runtime beyond the small helpers it exports: it does not mount components, match providers, or authorize calls. Pair it with an engine implementation.
|
|
80
|
+
- The types are compile-time only; nothing validates your components against the contract until TypeScript checks them.
|
|
81
|
+
|
|
82
|
+
## Related packages
|
|
83
|
+
|
|
84
|
+
- [`@godspeedai/cognate-kernel-cordis`](https://www.npmjs.com/package/@godspeedai/cognate-kernel-cordis) — the kernel engine implementation of this contract.
|
|
85
|
+
- [`@godspeedai/cognate-runtime-bun`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-bun) — the reference runtime that embeds the kernel.
|
|
86
|
+
- [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) — the SDK umbrella; the easiest way to get a working kernel-backed runtime.
|
|
87
|
+
|
|
88
|
+
## License
|
|
89
|
+
|
|
90
|
+
Apache-2.0
|
package/package.json
CHANGED