@godspeedai/cognate-kernel-api 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# @godspeedai/cognate-kernel-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-owned kernel contract (spec §8, §8.5, §9.1, §32): `Kernel`, `Scope`, `Component`, `FiberContext`, `CapabilityLease`, `Effects`, `Policy`.
+No engine type appears here; engines (e.g. `@godspeedai/cognate-kernel-cordis`) implement `KernelFactory`.
+
+- `@godspeedai/cognate-kernel-api` — types, `isCompatible` (deterministic eligibility), policies (`denyAll` default), typed errors.
+- `@godspeedai/cognate-kernel-api/conformance` — the executable contract. Every engine runs all six suites unchanged.
+
+Semantics that the suites pin down:
+- resolution never consults policy; every invocation does (default deny) and emits an `invocation` audit event;
+- invocation never throws: it returns `InvocationResult` (`unavailable | denied | deadline_exceeded | cancelled | failed`);
+- activation is all-or-nothing; failed setup disposes that attempt's effects in reverse order and publishes nothing;
+- dispose is idempotent, runs every disposer in reverse order, and rejects once with `CleanupError`;
+- a provider is visible in its scope and descendants only; closing a scope closes children first.

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@godspeedai/cognate-kernel-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Framework-owned kernel contract: contexts, scopes, capabilities, components, fibers, effects. No engine types.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GodSpeedAI/Cognate.git",
+    "directory": "packages/kernel-api"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./conformance": "./src/conformance/index.ts"
+  },
+  "peerDependencies": {}
+}

package/src/compat.ts

@@ -0,0 +1,25 @@
+import type { CapabilityContract, Requirement } from "./types.ts";
+
+function parse(version: string): [number, number, number] {
+  const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(version);
+  if (!match) throw new TypeError(`Invalid capability version: ${version}`);
+  return [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)];
+}
+
+/**
+ * Deterministic eligibility of a contract for a requirement (spec §8.2): same identity,
+ * same major version with minor/patch >= required, and every required attribute equal.
+ */
+export function isCompatible(requirement: Requirement, contract: CapabilityContract): boolean {
+  if (requirement.capability !== contract.id) return false;
+  if (requirement.version !== undefined) {
+    const [rMajor, rMinor, rPatch] = parse(requirement.version);
+    const [cMajor, cMinor, cPatch] = parse(contract.version);
+    if (rMajor !== cMajor) return false;
+    if (cMinor < rMinor || (cMinor === rMinor && cPatch < rPatch)) return false;
+  }
+  for (const [key, value] of Object.entries(requirement.attributes ?? {})) {
+    if (contract.attributes?.[key] !== value) return false;
+  }
+  return true;
+}

package/src/conformance/harness.ts

@@ -0,0 +1,80 @@
+import { allowCapabilities } from "../policy.ts";
+import type {
+  CapabilityContract,
+  Component,
+  InvocationContext,
+  Kernel,
+  KernelEvent,
+  KernelFactory,
+  Policy,
+  Principal,
+} from "../types.ts";
+
+export const system: Principal = { id: "system", kind: "system" };
+export const alice: Principal = { id: "alice", kind: "user" };
+
+export function contract(id: string, version = "1.0.0", attributes?: CapabilityContract["attributes"]): CapabilityContract {
+  return attributes ? { id, version, attributes } : { id, version };
+}
+
+export function invocation(overrides: Partial<InvocationContext> = {}): InvocationContext {
+  return { actor: alice, correlationId: "corr-1", ...overrides };
+}
+
+/** A kernel plus a recorded event log, closed after each test by the suite. */
+export interface Harness {
+  kernel: Kernel;
+  events: KernelEvent[];
+  /** Ordered record of side effects performed by test components (setup/teardown markers). */
+  log: string[];
+}
+
+export async function harness(factory: KernelFactory, policy: Policy = allowCapabilities("test-allow", ["*"])): Promise<Harness> {
+  const kernel = await factory({ tenant: "tenant-a", principal: system, policy });
+  const events: KernelEvent[] = [];
+  kernel.observe((event) => events.push(event));
+  return { kernel, events, log: [] };
+}
+
+/** Policy that allows every capability (tests that are not about authority). */
+export const allowAll: Policy = {
+  authorize: () => ({ allow: true, policyId: "allow-all", reason: "test" }),
+};
+
+/** A pure provider: provides `id` and records setup/teardown in the log. */
+export function provider(h: Harness, name: string, capability: CapabilityContract, handler: (input: unknown) => unknown = (input) => ({ from: name, input })): Component {
+  return {
+    id: name,
+    provides: [capability],
+    activate(fiber) {
+      h.log.push(`${name}:up`);
+      fiber.effects.register(() => void h.log.push(`${name}:down`), `${name}-marker`);
+      fiber.provide(capability, (input) => handler(input));
+    },
+  };
+}
+
+/** A consumer requiring the given capabilities under `dep0..n` names. */
+export function consumer(h: Harness, name: string, requires: Component["requires"], provides: CapabilityContract[] = []): Component {
+  return {
+    id: name,
+    requires,
+    provides,
+    activate(fiber) {
+      h.log.push(`${name}:up`);
+      fiber.effects.register(() => void h.log.push(`${name}:down`), `${name}-marker`);
+      for (const capability of provides) fiber.provide(capability, () => name);
+    },
+  };
+}
+
+export const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/** Wait until `predicate` holds or fail after `timeoutMs`. */
+export async function until(predicate: () => boolean, timeoutMs = 2000, what = "condition"): Promise<void> {
+  const start = Date.now();
+  while (!predicate()) {
+    if (Date.now() - start > timeoutMs) throw new Error(`Timed out waiting for ${what}`);
+    await delay(2);
+  }
+}

package/src/conformance/index.ts

@@ -0,0 +1,3 @@
+// Executable kernel contract. Engine adapters call every suite from their own tests.
+export { contractSuite, lifecycleSuite, effectsSuite, dependenciesSuite, scopesSuite, authoritySuite } from "./suites.ts";
+export * as fixtures from "./harness.ts";

package/src/conformance/suites.ts

@@ -0,0 +1,645 @@
+// Kernel conformance kit. Every kernel engine adapter must pass every suite unchanged.
+import { afterEach, describe, expect, test } from "bun:test";
+import { CleanupError, PermanentActivationError, UndeclaredCapabilityError } from "../errors.ts";
+import { isUnavailable } from "../index.ts";
+import { denyAll } from "../policy.ts";
+import type { CapabilityLease, ComponentHandle, KernelFactory, Policy } from "../types.ts";
+import { alice, allowAll, consumer, contract, delay, type Harness, harness, invocation, provider, until } from "./harness.ts";
+
+function lifecycleOf(factory: KernelFactory, policy: Policy = allowAll) {
+  const open: Harness[] = [];
+  afterEach(async () => {
+    for (const h of open.splice(0)) await h.kernel.shutdown("test end").catch(() => {});
+  });
+  return async (p: Policy = policy) => {
+    const h = await harness(factory, p);
+    open.push(h);
+    return h;
+  };
+}
+
+const lease = (value: unknown): CapabilityLease => {
+  if (isUnavailable(value as never)) throw new Error("expected a lease");
+  return value as CapabilityLease;
+};
+
+/** §8.5 operations and failure semantics. Gate: CG-KRN-001. */
+export function contractSuite(name: string, factory: KernelFactory): void {
+  describe(`${name}: kernel contract (§8.5)`, () => {
+    const make = lifecycleOf(factory);
+
+    test("a component without requirements activates and exposes a fiber", async () => {
+      const h = await make();
+      const handle = await h.kernel.mount(provider(h, "a", contract("x.read")));
+      await handle.waitFor("ACTIVE");
+      expect(handle.state).toBe("ACTIVE");
+      expect(handle.fiberId).toBeString();
+      expect(h.log).toEqual(["a:up"]);
+    });
+
+    test("missing dependencies keep a component WAITING with no fiber", async () => {
+      const h = await make();
+      const handle = await h.kernel.mount(consumer(h, "b", { dep: { capability: "x.read" } }));
+      await delay(20);
+      expect(handle.state).toBe("WAITING");
+      expect(handle.fiberId).toBeUndefined();
+      expect(h.log).toEqual([]);
+    });
+
+    test("resolve returns Unavailable, then a lease once provided, without consulting policy", async () => {
+      let consulted = 0;
+      const h = await make({ authorize: () => (consulted++, { allow: true, policyId: "p", reason: "r" }) });
+      expect(isUnavailable(h.kernel.resolve({ capability: "x.read" }))).toBe(true);
+      await (await h.kernel.mount(provider(h, "a", contract("x.read")))).waitFor("ACTIVE");
+      const resolved = lease(h.kernel.resolve({ capability: "x.read" }));
+      expect(resolved.valid).toBe(true);
+      expect(resolved.contract.id).toBe("x.read");
+      expect(consulted).toBe(0);
+    });
+
+    test("invoke passes input and full handler context and returns an ok result", async () => {
+      const h = await make();
+      let seen: Record<string, unknown> = {};
+      await (
+        await h.kernel.mount({
+          id: "a",
+          provides: [contract("x.read")],
+          activate(fiber) {
+            fiber.provide(contract("x.read"), (input, ctx) => {
+              seen = { actor: ctx.actor.id, correlationId: ctx.correlationId, providerId: ctx.providerId, tenant: ctx.tenant, allow: ctx.decision.allow, aborted: ctx.signal.aborted };
+              return { echo: input };
+            });
+          },
+        })
+      ).waitFor("ACTIVE");
+      const result = await lease(h.kernel.resolve({ capability: "x.read" })).invoke({ n: 1 }, invocation());
+      expect(result).toEqual({ ok: true, value: { echo: { n: 1 } } });
+      expect(seen).toMatchObject({ actor: "alice", correlationId: "corr-1", tenant: "tenant-a", allow: true, aborted: false });
+      expect(seen.providerId).toBeString();
+    });
+
+    test("a handler error is a typed failed result, not a thrown exception", async () => {
+      const h = await make();
+      await (await h.kernel.mount(provider(h, "a", contract("x.read"), () => { throw new Error("boom"); }))).waitFor("ACTIVE");
+      const result = await lease(h.kernel.resolve({ capability: "x.read" })).invoke(null, invocation());
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.failure.kind).toBe("failed");
+      }
+    });
+
+    test("a deadline yields deadline_exceeded and aborts the handler signal", async () => {
+      const h = await make();
+      let aborted = false;
+      await (
+        await h.kernel.mount({
+          id: "slow",
+          provides: [contract("x.slow")],
+          activate(fiber) {
+            fiber.provide(contract("x.slow"), async (_input, ctx) => {
+              await delay(200);
+              aborted = ctx.signal.aborted;
+              return "late";
+            });
+          },
+        })
+      ).waitFor("ACTIVE");
+      const result = await lease(h.kernel.resolve({ capability: "x.slow" })).invoke(null, invocation({ deadline: Date.now() + 20 }));
+      expect(result).toEqual({ ok: false, failure: { kind: "deadline_exceeded" } });
+      await until(() => aborted, 1000, "handler to observe abort");
+    });
+
+    test("caller cancellation yields cancelled", async () => {
+      const h = await make();
+      await (await h.kernel.mount(provider(h, "a", contract("x.wait"), () => delay(200)))).waitFor("ACTIVE");
+      const controller = new AbortController();
+      const pending = lease(h.kernel.resolve({ capability: "x.wait" })).invoke(null, invocation({ signal: controller.signal }));
+      controller.abort();
+      expect(await pending).toEqual({ ok: false, failure: { kind: "cancelled" } });
+    });
+
+    test("providing an undeclared capability fails activation and publishes nothing", async () => {
+      const h = await make();
+      const handle = await h.kernel.mount({
+        id: "liar",
+        provides: [contract("x.declared")],
+        retry: { maxAttempts: 1, baseDelayMs: 1, maxDelayMs: 1 },
+        activate(fiber) {
+          fiber.provide(contract("x.undeclared"), () => 1);
+        },
+      });
+      await handle.waitFor("FAILED");
+      expect(handle.lastError).toBeInstanceOf(UndeclaredCapabilityError);
+      expect(isUnavailable(h.kernel.resolve({ capability: "x.undeclared" }))).toBe(true);
+      expect(isUnavailable(h.kernel.resolve({ capability: "x.declared" }))).toBe(true);
+    });
+
+    test("dispose is idempotent and ends DISPOSED; the lease becomes unavailable", async () => {
+      const h = await make();
+      const handle = await h.kernel.mount(provider(h, "a", contract("x.read")));
+      await handle.waitFor("ACTIVE");
+      const held = lease(h.kernel.resolve({ capability: "x.read" }));
+      await handle.dispose("done");
+      await handle.dispose("again");
+      expect(handle.state).toBe("DISPOSED");
+      expect(h.log).toEqual(["a:up", "a:down"]);
+      expect(held.valid).toBe(false);
+      const result = await held.invoke(null, invocation());
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.failure.kind).toBe("unavailable");
+    });
+
+    test("an effect handle can be disposed early exactly once", async () => {
+      const h = await make();
+      let runs = 0;
+      let handleRef: { dispose(): Promise<void>; disposed: boolean } | undefined;
+      const handle = await h.kernel.mount({
+        id: "e",
+        activate(fiber) {
+          handleRef = fiber.effects.register(() => void runs++, "counter");
+        },
+      });
+      await handle.waitFor("ACTIVE");
+      await handleRef!.dispose();
+      await handleRef!.dispose();
+      expect(handleRef!.disposed).toBe(true);
+      await handle.dispose("done");
+      expect(runs).toBe(1);
+    });
+
+    test("closing a scope disposes its components", async () => {
+      const h = await make();
+      const scope = h.kernel.root.child({ id: "s1" });
+      const handle = await h.kernel.mount(provider(h, "a", contract("x.read")), scope);
+      await handle.waitFor("ACTIVE");
+      await scope.close("done");
+      expect(scope.closed).toBe(true);
+      expect(handle.state).toBe("DISPOSED");
+      expect(h.log).toEqual(["a:up", "a:down"]);
+    });
+
+    test("a component definition is independent of its occurrences (§8.3)", async () => {
+      const h1 = await make();
+      const h2 = await make();
+      const registry: string[] = [];
+      let activations = 0;
+      const definition: import("../types.ts").Component = {
+        id: "shared-definition",
+        provides: [contract("x.shared")],
+        activate(fiber) {
+          activations++;
+          registry.push(fiber.fiberId);
+          fiber.effects.register(() => void registry.splice(registry.indexOf(fiber.fiberId), 1), "entry");
+          fiber.provide(contract("x.shared"), () => fiber.fiberId);
+        },
+      };
+      const a = h1.kernel.root.child({ id: "a" });
+      const b = h1.kernel.root.child({ id: "b" });
+      const occurrences = [await h1.kernel.mount(definition, a), await h1.kernel.mount(definition, b), await h2.kernel.mount(definition)];
+      for (const o of occurrences) await o.waitFor("ACTIVE");
+      expect(activations).toBe(3);
+      expect(new Set(occurrences.map((o) => o.fiberId)).size).toBe(3);
+      await occurrences[0]!.dispose("one occurrence");
+      expect(occurrences.slice(1).map((o) => o.state)).toEqual(["ACTIVE", "ACTIVE"]);
+      expect(registry).toEqual([occurrences[1]!.fiberId!, occurrences[2]!.fiberId!]);
+      const fromB = lease(h1.kernel.resolve({ capability: "x.shared" }, b));
+      expect(await fromB.invoke(null, invocation())).toEqual({ ok: true, value: occurrences[1]!.fiberId });
+      expect(isUnavailable(h1.kernel.resolve({ capability: "x.shared" }, a))).toBe(true);
+    });
+
+    test("mounting into a closed scope is rejected", async () => {
+      const h = await make();
+      const scope = h.kernel.root.child();
+      await scope.close("done");
+      await expect(h.kernel.mount(provider(h, "a", contract("x.read")), scope)).rejects.toThrow();
+    });
+  });
+}
+
+/** §8.4 lifecycle: FAILED, bounded retry, permanent failure, activation races. Gate: CG-KRN-002. */
+export function lifecycleSuite(name: string, factory: KernelFactory): void {
+  describe(`${name}: fiber lifecycle (§8.4)`, () => {
+    const make = lifecycleOf(factory);
+
+    test("a transient activation failure passes through FAILED and retries to ACTIVE", async () => {
+      const h = await make();
+      let attempts = 0;
+      const handle = await h.kernel.mount({
+        id: "flaky",
+        retry: { maxAttempts: 3, baseDelayMs: 5, maxDelayMs: 20 },
+        activate() {
+          attempts++;
+          if (attempts === 1) throw new Error("transient");
+        },
+      });
+      await handle.waitFor("ACTIVE");
+      expect(attempts).toBe(2);
+      const states = h.events.filter((e) => e.type === "fiber.state").map((e) => (e.type === "fiber.state" ? e.to : ""));
+      expect(states).toEqual(["ACTIVATING", "FAILED", "WAITING", "ACTIVATING", "ACTIVE"]);
+    });
+
+    test("a permanent failure stays FAILED until reset", async () => {
+      const h = await make();
+      let attempts = 0;
+      const handle = await h.kernel.mount({
+        id: "broken",
+        retry: { maxAttempts: 5, baseDelayMs: 1, maxDelayMs: 5 },
+        activate() {
+          attempts++;
+          if (attempts === 1) throw new PermanentActivationError("bad config");
+        },
+      });
+      await handle.waitFor("FAILED");
+      await delay(30);
+      expect(handle.state).toBe("FAILED");
+      expect(attempts).toBe(1);
+      expect(handle.lastError).toBeInstanceOf(PermanentActivationError);
+      await handle.reset();
+      await handle.waitFor("ACTIVE");
+      expect(attempts).toBe(2);
+    });
+
+    test("retries are bounded: exhausting maxAttempts leaves the component FAILED", async () => {
+      const h = await make();
+      let attempts = 0;
+      const handle = await h.kernel.mount({
+        id: "always",
+        retry: { maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 4 },
+        activate() {
+          attempts++;
+          throw new Error("nope");
+        },
+      });
+      await until(() => attempts === 3, 1000, "three attempts");
+      await handle.waitFor("FAILED");
+      await delay(30);
+      expect(attempts).toBe(3);
+      expect(handle.state).toBe("FAILED");
+    });
+
+    test("an activation that never settles fails by timeout instead of staying ACTIVATING", async () => {
+      const h = await make();
+      const handle = await h.kernel.mount({
+        id: "hang",
+        activationTimeoutMs: 30,
+        retry: { maxAttempts: 1, baseDelayMs: 1, maxDelayMs: 1 },
+        activate: () => new Promise<void>(() => {}),
+      });
+      await handle.waitFor("FAILED", 1000);
+      expect(handle.state).toBe("FAILED");
+    });
+
+    test("a timed-out activation still disposes the effects it registered before hanging", async () => {
+      const h = await make();
+      const handle = await h.kernel.mount({
+        id: "hang-after-effect",
+        activationTimeoutMs: 30,
+        retry: { maxAttempts: 1, baseDelayMs: 1, maxDelayMs: 1 },
+        async activate(fiber) {
+          fiber.effects.register(() => void h.log.push("partial:down"), "partial");
+          await new Promise<void>(() => {});
+        },
+      });
+      await handle.waitFor("FAILED", 1000);
+      await until(() => h.log.includes("partial:down"), 1000, "partial effect disposal after timeout");
+      expect(h.log).toEqual(["partial:down"]);
+    });
+
+    test("dispose during a pending activation wins, cleans partial effects, and publishes nothing", async () => {
+      const h = await make();
+      let release!: () => void;
+      const gate = new Promise<void>((resolve) => (release = resolve));
+      let aborted = false;
+      const handle = await h.kernel.mount({
+        id: "racy",
+        provides: [contract("x.racy")],
+        async activate(fiber) {
+          fiber.effects.register(() => void h.log.push("partial:down"), "partial");
+          await gate;
+          aborted = fiber.signal.aborted;
+          fiber.provide(contract("x.racy"), () => 1);
+        },
+      });
+      await handle.waitFor("ACTIVATING");
+      const disposing = handle.dispose("race");
+      release();
+      await disposing.catch(() => {});
+      await delay(10);
+      expect(handle.state).toBe("DISPOSED");
+      expect(aborted).toBe(true);
+      expect(h.log).toEqual(["partial:down"]);
+      expect(isUnavailable(h.kernel.resolve({ capability: "x.racy" }))).toBe(true);
+      expect(h.events.some((e) => e.type === "fiber.state" && e.to === "ACTIVE")).toBe(false);
+    });
+
+    test("repeated dependency notifications never create duplicate active instances", async () => {
+      const h = await make();
+      let activations = 0;
+      const handle = await h.kernel.mount({
+        id: "dependent",
+        requires: { dep: { capability: "x.read" } },
+        activate() {
+          activations++;
+        },
+      });
+      await Promise.all([
+        h.kernel.mount(provider(h, "p1", contract("x.read"))),
+        h.kernel.mount(provider(h, "p2", contract("x.read"))),
+        h.kernel.mount(provider(h, "p3", contract("x.read"))),
+      ]);
+      await handle.waitFor("ACTIVE");
+      await delay(30);
+      expect(activations).toBe(1);
+      expect(handle.state).toBe("ACTIVE");
+    });
+  });
+}
+
+/** §9.1 / §31.1 reversible effects. Gate: CG-KRN-003. */
+export function effectsSuite(name: string, factory: KernelFactory): void {
+  describe(`${name}: reversible effects (§9.1)`, () => {
+    const make = lifecycleOf(factory);
+
+    test("disposers run in reverse registration order", async () => {
+      const h = await make();
+      const handle = await h.kernel.mount({
+        id: "ordered",
+        activate(fiber) {
+          for (const label of ["listener", "tool", "renderer", "timer"]) fiber.effects.register(() => void h.log.push(label), label);
+        },
+      });
+      await handle.waitFor("ACTIVE");
+      await handle.dispose("done");
+      expect(h.log).toEqual(["timer", "renderer", "tool", "listener"]);
+    });
+
+    test("a failing disposer does not stop the others; errors are aggregated once", async () => {
+      const h = await make();
+      const handle = await h.kernel.mount({
+        id: "messy",
+        activate(fiber) {
+          fiber.effects.register(() => void h.log.push("first"), "first");
+          fiber.effects.register(() => { throw new Error("second failed"); }, "second");
+          fiber.effects.register(() => void h.log.push("third"), "third");
+        },
+      });
+      await handle.waitFor("ACTIVE");
+      const error = await handle.dispose("done").then(() => undefined, (e: unknown) => e);
+      expect(error).toBeInstanceOf(CleanupError);
+      expect((error as CleanupError).errors).toHaveLength(1);
+      expect(h.log).toEqual(["third", "first"]);
+      await handle.dispose("again");
+      expect(h.log).toEqual(["third", "first"]);
+    });
+
+    test("failed setup disposes every effect from that attempt in reverse order", async () => {
+      const h = await make();
+      const handle = await h.kernel.mount({
+        id: "half",
+        provides: [contract("x.half")],
+        retry: { maxAttempts: 1, baseDelayMs: 1, maxDelayMs: 1 },
+        activate(fiber) {
+          fiber.effects.register(() => void h.log.push("a"), "a");
+          fiber.effects.register(() => void h.log.push("b"), "b");
+          fiber.provide(contract("x.half"), () => 1);
+          throw new Error("setup failed");
+        },
+      });
+      await handle.waitFor("FAILED");
+      expect(h.log).toEqual(["b", "a"]);
+      expect(isUnavailable(h.kernel.resolve({ capability: "x.half" }))).toBe(true);
+      expect(h.events.some((e) => e.type === "capability.provided")).toBe(false);
+    });
+
+    test("cleanup errors during dependency loss are observable as cleanup.failed", async () => {
+      const h = await make();
+      const p = await h.kernel.mount(provider(h, "p", contract("x.read")));
+      const c = await h.kernel.mount({
+        id: "c",
+        requires: { dep: { capability: "x.read" } },
+        activate(fiber) {
+          fiber.effects.register(() => { throw new Error("teardown bug"); }, "bad");
+        },
+      });
+      await c.waitFor("ACTIVE");
+      await p.dispose("gone");
+      await c.waitFor("WAITING");
+      expect(h.events.some((e) => e.type === "cleanup.failed" && e.componentId === "c")).toBe(true);
+    });
+
+    test("mount then unmount returns owned observable state to its initial value", async () => {
+      const h = await make();
+      const registry = new Set<string>();
+      const before = [...registry];
+      const handle = await h.kernel.mount({
+        id: "reg",
+        activate(fiber) {
+          for (const key of ["listener", "tool", "timer"]) {
+            registry.add(key);
+            fiber.effects.register(() => void registry.delete(key), key);
+          }
+        },
+      });
+      await handle.waitFor("ACTIVE");
+      expect(registry.size).toBe(3);
+      await handle.dispose("done");
+      expect([...registry]).toEqual(before);
+    });
+  });
+}
+
+/** §8.4 / §29.2 / §35 dependency closure and replacement. Gate: CG-KRN-004. */
+export function dependenciesSuite(name: string, factory: KernelFactory): void {
+  describe(`${name}: dependency closure (§8.4, §35)`, () => {
+    const make = lifecycleOf(factory);
+
+    test("provide → activate, remove → deactivate, restore compatible → reactivate on the new provider", async () => {
+      const h = await make();
+      const b = await h.kernel.mount(consumer(h, "b", { dep: { capability: "customer.read", version: "1.0" } }));
+      expect(b.state).toBe("WAITING");
+      const a1 = await h.kernel.mount(provider(h, "a1", contract("customer.read", "1.2.0")));
+      await b.waitFor("ACTIVE");
+      const firstFiber = b.fiberId;
+      await a1.dispose("removed");
+      await b.waitFor("WAITING");
+      expect(b.fiberId).toBeUndefined();
+      const a2 = await h.kernel.mount(provider(h, "a2", contract("customer.read", "1.5.0")));
+      await b.waitFor("ACTIVE");
+      expect(b.fiberId).not.toBe(firstFiber);
+      expect(lease(h.kernel.resolve({ capability: "customer.read" })).providerId).toBeString();
+      expect(h.log).toEqual(["b:up".replace("b", "a1"), "b:up", "b:down", "a1:down", "a2:up", "b:up"]);
+      await a2.dispose("end");
+    });
+
+    test("incompatible versions and attributes are not eligible", async () => {
+      const h = await make();
+      const b = await h.kernel.mount(consumer(h, "b", { dep: { capability: "m.gen", version: "1.2", attributes: { structured_output: true } } }));
+      await h.kernel.mount(provider(h, "old", contract("m.gen", "1.1.0", { structured_output: true })));
+      await h.kernel.mount(provider(h, "next", contract("m.gen", "2.0.0", { structured_output: true })));
+      await h.kernel.mount(provider(h, "plain", contract("m.gen", "1.3.0")));
+      await delay(20);
+      expect(b.state).toBe("WAITING");
+      await h.kernel.mount(provider(h, "good", contract("m.gen", "1.3.0", { structured_output: true })));
+      await b.waitFor("ACTIVE");
+    });
+
+    test("loss propagates transitively through dependent chains", async () => {
+      const h = await make();
+      const a = await h.kernel.mount(provider(h, "a", contract("x.a")));
+      const b = await h.kernel.mount(consumer(h, "b", { dep: { capability: "x.a" } }, [contract("x.b")]));
+      const c = await h.kernel.mount(consumer(h, "c", { dep: { capability: "x.b" } }));
+      await c.waitFor("ACTIVE");
+      await a.dispose("gone");
+      await b.waitFor("WAITING");
+      await c.waitFor("WAITING");
+      expect(h.log.slice(-3)).toEqual(["c:down", "b:down", "a:down"]);
+    });
+
+    test("losing the bound provider while another compatible one remains rebinds to it", async () => {
+      const h = await make();
+      const p1 = await h.kernel.mount(provider(h, "p1", contract("x.read")));
+      await p1.waitFor("ACTIVE");
+      const p2 = await h.kernel.mount(provider(h, "p2", contract("x.read")));
+      await p2.waitFor("ACTIVE");
+      let bound: CapabilityLease | undefined;
+      const b = await h.kernel.mount({
+        id: "b",
+        requires: { dep: { capability: "x.read" } },
+        activate(fiber) {
+          bound = fiber.dependencies.dep;
+        },
+      });
+      await b.waitFor("ACTIVE");
+      const first = bound!;
+      const firstResult = await first.invoke(null, invocation());
+      const firstFrom = firstResult.ok ? (firstResult.value as { from: string }).from : "";
+      await (firstFrom === "p1" ? p1 : p2).dispose("gone");
+      await until(() => b.state === "ACTIVE" && bound !== first, 1000, "rebinding");
+      const second = await bound!.invoke(null, invocation());
+      expect(second.ok).toBe(true);
+      if (second.ok) expect((second.value as { from: string }).from).toBe(firstFrom === "p1" ? "p2" : "p1");
+    });
+  });
+}
+
+/** §8.1 / §32 scope isolation. Gate: CG-KRN-005. */
+export function scopesSuite(name: string, factory: KernelFactory): void {
+  describe(`${name}: scope isolation (§8.1)`, () => {
+    const make = lifecycleOf(factory);
+
+    test("a child-provided capability is invisible to parent and siblings, visible to descendants", async () => {
+      const h = await make();
+      const child = h.kernel.root.child({ id: "child" });
+      const sibling = h.kernel.root.child({ id: "sibling" });
+      const grandchild = child.child({ id: "grandchild" });
+      await (await h.kernel.mount(provider(h, "p", contract("x.secret")), child)).waitFor("ACTIVE");
+      expect(isUnavailable(h.kernel.resolve({ capability: "x.secret" }, h.kernel.root))).toBe(true);
+      expect(isUnavailable(h.kernel.resolve({ capability: "x.secret" }, sibling))).toBe(true);
+      expect(isUnavailable(h.kernel.resolve({ capability: "x.secret" }, grandchild))).toBe(false);
+      const siblingConsumer = await h.kernel.mount(consumer(h, "s", { dep: { capability: "x.secret" } }), sibling);
+      await delay(20);
+      expect(siblingConsumer.state).toBe("WAITING");
+    });
+
+    test("parent-provided capabilities are visible in children", async () => {
+      const h = await make();
+      await (await h.kernel.mount(provider(h, "p", contract("x.shared")))).waitFor("ACTIVE");
+      const child = h.kernel.root.child();
+      const c = await h.kernel.mount(consumer(h, "c", { dep: { capability: "x.shared" } }), child);
+      await c.waitFor("ACTIVE");
+    });
+
+    test("a child may narrow its principal without changing the parent", async () => {
+      const h = await make();
+      const child = h.kernel.root.child({ principal: alice });
+      expect(child.principal.id).toBe("alice");
+      expect(h.kernel.root.principal.id).toBe("system");
+      expect(child.tenant).toBe(h.kernel.root.tenant);
+      expect(child.parentId).toBe(h.kernel.root.id);
+    });
+
+    test("closing a parent closes children before parent effects", async () => {
+      const h = await make();
+      const parent = h.kernel.root.child({ id: "parent" });
+      const child = parent.child({ id: "child" });
+      await (await h.kernel.mount(provider(h, "outer", contract("x.outer")), parent)).waitFor("ACTIVE");
+      await (await h.kernel.mount(provider(h, "inner", contract("x.inner")), child)).waitFor("ACTIVE");
+      await parent.close("done");
+      expect(child.closed).toBe(true);
+      expect(h.log).toEqual(["outer:up", "inner:up", "inner:down", "outer:down"]);
+    });
+
+    test("closing a child leaves the parent's components active", async () => {
+      const h = await make();
+      const outer = await h.kernel.mount(provider(h, "outer", contract("x.outer")));
+      await outer.waitFor("ACTIVE");
+      const child = h.kernel.root.child();
+      await (await h.kernel.mount(provider(h, "inner", contract("x.inner")), child)).waitFor("ACTIVE");
+      await child.close("done");
+      expect(outer.state).toBe("ACTIVE");
+    });
+  });
+}
+
+/** §8.5 / §32 authority. Gate: CG-KRN-006. */
+export function authoritySuite(name: string, factory: KernelFactory): void {
+  describe(`${name}: authority (§32)`, () => {
+    const make = lifecycleOf(factory);
+
+    test("default-deny policy denies invocation without calling the handler", async () => {
+      const h = await make(denyAll);
+      let called = false;
+      await (await h.kernel.mount(provider(h, "p", contract("x.pay"), () => (called = true)))).waitFor("ACTIVE");
+      const result = await lease(h.kernel.resolve({ capability: "x.pay" })).invoke(null, invocation());
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.failure.kind).toBe("denied");
+      }
+      expect(called).toBe(false);
+    });
+
+    test("policy receives actor, tenant, scope, capability, and provider for each invocation", async () => {
+      const requests: unknown[] = [];
+      const h = await make({ authorize: (r) => (requests.push(r), { allow: true, policyId: "p", reason: "ok" }) });
+      const scope = h.kernel.root.child({ id: "ws" });
+      await (await h.kernel.mount(provider(h, "p", contract("x.read")), scope)).waitFor("ACTIVE");
+      const l = lease(h.kernel.resolve({ capability: "x.read" }, scope));
+      await l.invoke(null, invocation());
+      await l.invoke(null, invocation({ correlationId: "corr-2" }));
+      expect(requests).toHaveLength(2);
+      expect(requests[0]).toMatchObject({ operation: "invoke", actor: { id: "alice" }, tenant: "tenant-a", scopeId: "ws", capability: { id: "x.read" }, providerId: l.providerId, correlationId: "corr-1" });
+    });
+
+    test("the caller's tenant reaches both the policy and the handler", async () => {
+      const seen: string[] = [];
+      const h = await make({ authorize: (r) => (seen.push(`policy:${r.tenant}`), { allow: true, policyId: "p", reason: "ok" }) });
+      await (
+        await h.kernel.mount({ id: "t", provides: [contract("x.tenant")], activate: (f) => f.provide(contract("x.tenant"), (_i, ctx) => void seen.push(`handler:${ctx.tenant}`)) })
+      ).waitFor("ACTIVE");
+      const l = lease(h.kernel.resolve({ capability: "x.tenant" }));
+      await l.invoke(null, invocation({ tenant: "tenant-b" }));
+      await l.invoke(null, invocation());
+      expect(seen).toEqual(["policy:tenant-b", "handler:tenant-b", "policy:tenant-a", "handler:tenant-a"]);
+    });
+
+    test("every invocation emits an auditable decision event", async () => {
+      const h = await make(denyAll);
+      await (await h.kernel.mount(provider(h, "p", contract("x.pay")))).waitFor("ACTIVE");
+      await lease(h.kernel.resolve({ capability: "x.pay" })).invoke(null, invocation({ correlationId: "audit-1" }));
+      const audit = h.events.find((e) => e.type === "invocation");
+      expect(audit).toMatchObject({ type: "invocation", capability: "x.pay", correlationId: "audit-1", decision: { allow: false, policyId: "deny-all" } });
+    });
+
+    test("a revoked lease yields unavailable before any policy check", async () => {
+      let consulted = 0;
+      const h = await make({ authorize: () => (consulted++, { allow: true, policyId: "p", reason: "r" }) });
+      const handle: ComponentHandle = await h.kernel.mount(provider(h, "p", contract("x.read")));
+      await handle.waitFor("ACTIVE");
+      const l = lease(h.kernel.resolve({ capability: "x.read" }));
+      await handle.dispose("revoked");
+      const result = await l.invoke(null, invocation());
+      expect(result).toMatchObject({ ok: false, failure: { kind: "unavailable" } });
+      expect(consulted).toBe(0);
+    });
+  });
+}

package/src/errors.ts

@@ -0,0 +1,29 @@
+/** Aggregated disposer failures from one teardown (spec §8.5, §31.1). */
+export class CleanupError extends AggregateError {
+  override readonly name = "CleanupError";
+  constructor(
+    readonly componentId: string,
+    errors: readonly unknown[],
+  ) {
+    super(errors, `${errors.length} disposer(s) failed while tearing down ${componentId}`);
+  }
+}
+
+/** Throw from `activate` to mark a failure that retrying cannot fix; requires `reset()`. */
+export class PermanentActivationError extends Error {
+  override readonly name = "PermanentActivationError";
+}
+
+/** Activation exceeded its timeout; treated as a transient failure. */
+export class ActivationTimeoutError extends Error {
+  override readonly name = "ActivationTimeoutError";
+}
+
+/** A component tried to provide a capability it did not declare. */
+export class UndeclaredCapabilityError extends Error {
+  override readonly name = "UndeclaredCapabilityError";
+}
+
+export class ScopeClosedError extends Error {
+  override readonly name = "ScopeClosedError";
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export type * from "./types.ts";
+export { isCompatible } from "./compat.ts";
+export { denyAll, rulePolicy, allowCapabilities, type Rule } from "./policy.ts";
+export { CleanupError, PermanentActivationError, ActivationTimeoutError, UndeclaredCapabilityError, ScopeClosedError } from "./errors.ts";
+
+/** Type guard distinguishing an unavailable resolution from a lease. */
+export function isUnavailable(value: import("./types.ts").CapabilityLease | import("./types.ts").Unavailable): value is import("./types.ts").Unavailable {
+  return "unavailable" in value && value.unavailable === true;
+}

package/src/policy.ts

@@ -0,0 +1,29 @@
+import type { AuthorizationRequest, Policy, PolicyDecision } from "./types.ts";
+
+/** Default policy: no authority (spec §32). */
+export const denyAll: Policy = {
+  authorize: () => ({ allow: false, policyId: "deny-all", reason: "no policy grants this invocation" }),
+};
+
+export type Rule = (request: AuthorizationRequest) => PolicyDecision | undefined;
+
+/** First matching rule decides; no match denies. */
+export function rulePolicy(policyId: string, rules: readonly Rule[]): Policy {
+  return {
+    authorize(request) {
+      for (const rule of rules) {
+        const decision = rule(request);
+        if (decision) return decision;
+      }
+      return { allow: false, policyId, reason: "no rule matched" };
+    },
+  };
+}
+
+/** Allow invocations of the listed capability ids by any actor. Intended for tests and profiles that state it explicitly. */
+export function allowCapabilities(policyId: string, capabilities: readonly string[]): Policy {
+  const allowed = new Set(capabilities);
+  return rulePolicy(policyId, [
+    (request) => (allowed.has(request.capability.id) ? { allow: true, policyId, reason: `capability ${request.capability.id} allowed` } : undefined),
+  ]);
+}

package/src/types.ts

@@ -0,0 +1,233 @@
+// Framework-owned kernel contract (spec §8, §8.5, §9.1, §32). No engine types may appear here.
+
+/**
+ * Structurally identical to `@godspeedai/cognate-events`' `Json`, declared locally: `@godspeedai/cognate-events` itself
+ * depends on this package (for `SemanticRef`), so importing it here would cycle the package graph
+ * (spec §28). Any JSON value satisfies both structurally.
+ */
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+/** Opaque reference to an existing semantic object (spec §7.1). Produced by semantic adapters. */
+export interface SemanticRef {
+  readonly namespace: string;
+  /** DomainForge object identity (e.g. `namespace::name`). */
+  readonly id: string;
+  readonly kind?: string;
+  /** Model URI plus immutable source digest, or SemanticPack identity/version. */
+  readonly source: { readonly uri: string; readonly digest: string };
+  /** Cognate-owned adapter projection schema version. */
+  readonly projectionVersion: string;
+}
+
+export interface Principal {
+  readonly id: string;
+  readonly kind: "user" | "agent" | "service" | "system";
+}
+
+export type AttributeValue = string | number | boolean;
+export type Attributes = Readonly<Record<string, AttributeValue>>;
+
+/** A capability contract a provider publishes (spec §8.2). */
+export interface CapabilityContract {
+  /** Stable capability identity, e.g. `customer.read`. */
+  readonly id: string;
+  /** Semantic version of the contract, `MAJOR.MINOR.PATCH`. */
+  readonly version: string;
+  readonly attributes?: Attributes;
+  readonly semanticRef?: SemanticRef;
+}
+
+/** What a consumer requires (deterministic eligibility input, spec §8.2). */
+export interface Requirement {
+  readonly capability: string;
+  /** Required major version; any provider with the same major and >= minor is compatible. */
+  readonly version?: string;
+  /** Every listed attribute must equal the provider's attribute. */
+  readonly attributes?: Attributes;
+}
+
+export interface InvocationContext {
+  readonly actor: Principal;
+  /** The caller's tenant. Defaults to the kernel's tenant; policy and handlers see this value (spec §32). */
+  readonly tenant?: string;
+  readonly correlationId: string;
+  readonly causationId?: string;
+  readonly runId?: string;
+  /** Required for durable commands (spec §10). */
+  readonly idempotencyKey?: string;
+  /** Absolute deadline in epoch milliseconds. */
+  readonly deadline?: number;
+  readonly signal?: AbortSignal;
+  /**
+   * Durable progress channel into the invoking run, when there is one (e.g. streamed model token
+   * deltas). Absent, or a no-op, outside a run — e.g. `RuntimeService.invoke` from a client. Never
+   * affects step/emit/artifact replay accounting.
+   */
+  readonly progress?: (payload: Json) => Promise<void>;
+}
+
+export interface AuthorizationRequest {
+  readonly operation: "invoke";
+  readonly actor: Principal;
+  readonly tenant: string;
+  readonly scopeId: string;
+  readonly capability: CapabilityContract;
+  readonly providerId: string;
+  readonly correlationId: string;
+}
+
+export interface PolicyDecision {
+  readonly allow: boolean;
+  readonly policyId: string;
+  readonly reason: string;
+}
+
+/** Server-side policy consulted at every invocation. The default is deny (spec §32). */
+export interface Policy {
+  authorize(request: AuthorizationRequest): PolicyDecision | Promise<PolicyDecision>;
+}
+
+/** Context passed to a capability handler. */
+export interface HandlerContext extends InvocationContext {
+  readonly capability: CapabilityContract;
+  readonly providerId: string;
+  readonly decision: PolicyDecision;
+  readonly tenant: string;
+  readonly scopeId: string;
+  /** Aborted on caller cancellation, deadline expiry, or provider teardown. */
+  readonly signal: AbortSignal;
+}
+
+export type CapabilityHandler<I = unknown, O = unknown> = (input: I, context: HandlerContext) => O | Promise<O>;
+
+export type InvocationFailure =
+  | { readonly kind: "unavailable"; readonly capability: string; readonly reason: string }
+  | { readonly kind: "denied"; readonly decision: PolicyDecision }
+  | { readonly kind: "deadline_exceeded" }
+  | { readonly kind: "cancelled" }
+  | { readonly kind: "failed"; readonly error: unknown };
+
+export type InvocationResult<O> =
+  | { readonly ok: true; readonly value: O }
+  | { readonly ok: false; readonly failure: InvocationFailure };
+
+/** A resolved, revocable reference to one active provider. Resolution grants no permission. */
+export interface CapabilityLease<I = unknown, O = unknown> {
+  readonly contract: CapabilityContract;
+  readonly providerId: string;
+  /** False once the providing fiber leaves ACTIVE or its scope closes. */
+  readonly valid: boolean;
+  invoke(input: I, context: InvocationContext): Promise<InvocationResult<O>>;
+}
+
+export interface Unavailable {
+  readonly unavailable: true;
+  readonly requirement: Requirement;
+  readonly reason: string;
+}
+
+export interface EffectHandle {
+  readonly label: string;
+  readonly disposed: boolean;
+  /** Dispose this single effect early; idempotent. */
+  dispose(): Promise<void>;
+}
+
+export type Disposer = () => void | Promise<void>;
+
+export interface Effects {
+  /** Register a reversible effect owned by the current fiber (spec §9.1). */
+  register(disposer: Disposer, label?: string): EffectHandle;
+}
+
+export type FiberState = "WAITING" | "ACTIVATING" | "ACTIVE" | "FAILED" | "DEACTIVATING" | "DISPOSED";
+
+/** What an activation function receives: one live fiber (spec §8.4). */
+export interface FiberContext {
+  readonly fiberId: string;
+  readonly componentId: string;
+  readonly scope: Scope;
+  /** Leases for every declared requirement, keyed by requirement name. */
+  readonly dependencies: Readonly<Record<string, CapabilityLease>>;
+  readonly effects: Effects;
+  /** Aborted when a concurrent disposal or dependency loss wins over this activation. */
+  readonly signal: AbortSignal;
+  /** Publish a declared capability; becomes visible only after activation succeeds. */
+  provide<I, O>(contract: CapabilityContract, handler: CapabilityHandler<I, O>): void;
+}
+
+export interface RetryPolicy {
+  /** Attempts before the component becomes permanently FAILED. */
+  readonly maxAttempts: number;
+  readonly baseDelayMs: number;
+  readonly maxDelayMs: number;
+}
+
+/** A declarative unit of composition, independent from any running occurrence (spec §8.3). */
+export interface Component {
+  readonly id: string;
+  readonly requires?: Readonly<Record<string, Requirement>>;
+  readonly provides?: readonly CapabilityContract[];
+  readonly semanticRef?: SemanticRef;
+  readonly retry?: RetryPolicy;
+  /** Activation longer than this fails transiently instead of staying ACTIVATING (spec §8.4). Default 30000. */
+  readonly activationTimeoutMs?: number;
+  activate(fiber: FiberContext): void | Promise<void>;
+}
+
+export interface ComponentHandle {
+  readonly componentId: string;
+  readonly scopeId: string;
+  readonly state: FiberState;
+  /** The id of the current ACTIVE fiber, if any. */
+  readonly fiberId: string | undefined;
+  readonly lastError: unknown;
+  /** Resolve when the handle reaches a state (rejects on timeout). */
+  waitFor(state: FiberState, timeoutMs?: number): Promise<void>;
+  /** Permanently dispose; idempotent. Rejects once with CleanupError if any disposer failed. */
+  dispose(reason: string): Promise<void>;
+  /** Clear a permanent FAILED state and re-enter WAITING. */
+  reset(): Promise<void>;
+}
+
+export interface ScopeOptions {
+  readonly id?: string;
+  /** A child may narrow its principal; it never gains authority by inheritance. */
+  readonly principal?: Principal;
+}
+
+export interface Scope {
+  readonly id: string;
+  readonly parentId: string | undefined;
+  readonly tenant: string;
+  readonly principal: Principal;
+  readonly closed: boolean;
+  child(options?: ScopeOptions): Scope;
+  /** Close children first, then dispose this scope's components. */
+  close(reason: string): Promise<void>;
+}
+
+export type KernelEvent =
+  | { readonly type: "fiber.state"; readonly componentId: string; readonly scopeId: string; readonly fiberId: string | undefined; readonly from: FiberState; readonly to: FiberState; readonly error?: unknown }
+  | { readonly type: "capability.provided" | "capability.withdrawn"; readonly capability: CapabilityContract; readonly providerId: string; readonly scopeId: string }
+  | { readonly type: "cleanup.failed"; readonly componentId: string; readonly fiberId: string; readonly errors: readonly unknown[] }
+  | { readonly type: "invocation"; readonly capability: string; readonly providerId: string; readonly correlationId: string; readonly decision: PolicyDecision };
+
+export interface KernelOptions {
+  readonly tenant: string;
+  readonly principal: Principal;
+  readonly policy: Policy;
+  /** Deterministic id source for tests; defaults to crypto.randomUUID. */
+  readonly ids?: () => string;
+}
+
+export interface Kernel {
+  readonly root: Scope;
+  mount(component: Component, scope?: Scope): Promise<ComponentHandle>;
+  resolve(requirement: Requirement, scope?: Scope): CapabilityLease | Unavailable;
+  observe(listener: (event: KernelEvent) => void): () => void;
+  /** Close the root scope and release the engine. */
+  shutdown(reason: string): Promise<void>;
+}
+
+export type KernelFactory = (options: KernelOptions) => Kernel | Promise<Kernel>;