@godspeedai/cognate-kernel-cordis 0.0.0-stage → 0.1.0

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,33 @@
-# Temporary Holding Version
+# @godspeedai/cognate-kernel-cordis
 
-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.
+Cordis-backed implementation of `@godspeedai/cognate-kernel-api`. Only this package imports `cordis`; no
+Cordis type crosses an exported signature (spec §3.4). See `docs/decisions/ADR-0001-kernel-engine-cordis.md`.
+
+## Mapping
+
+| Cognate concept | Cordis concept |
+| --- | --- |
+| `Scope` | A Cordis `Context` obtained via `ctx.isolate(id)` (`scope.ts`) |
+| Mounted component occurrence | One `ctx.plugin()` call = one Cordis fiber, per attempt (`fiber.ts`) |
+| `effects.register()` | Entries in an adapter-owned stack unwound by a single `ctx.effect()` wrapper |
+| `provide()` / capability publish-withdraw | Committed into `CapabilityRegistry` only after activation succeeds, torn down by the same wrapper effect |
+| `CapabilityLease` | Adapter object bound to one `Publication`, revalidated per invoke (Cordis has no lease type) |
+| `kernel.resolve()` / dependency matching | `CapabilityRegistry.find()` using `isCompatible` over scope-ancestor chain |
+
+## Adapter-owned behaviours (Cordis has none of these; ADR-0001 mitigations)
+
+- **Aggregated cleanup errors** — Cordis reports each disposer error to its own logger and never
+  aggregates them; the single wrapper effect aggregates into `CleanupError` itself.
+- **Reverse-order disposal** — Cordis's own `Promise.all`-based unload is only reverse-of-completion
+  for synchronous disposers; the adapter runs its own effect stack sequentially in reverse.
+- **Cancellation signal** — Cordis never cancels an in-flight `apply()`; the adapter derives its own
+  `AbortSignal` per attempt and per active occurrence.
+- **Retry/backoff and permanent failure** — fully adapter-owned state machine (`fiber.ts`).
+- **Activation timeout** — raced against the Cordis fiber promise; a timed-out fiber is abandoned,
+  not force-disposed (Cordis's `dispose()` blocks forever on a hung `apply()`).
+- **FAILED/DEACTIVATING vocabulary and fiber-state translation** — Cordis uses
+  PENDING/LOADING/ACTIVE/FAILED/DISPOSED/UNLOADING; never exposed.
+- **Dependency eligibility (`isCompatible`, version/attributes)** and **scope visibility**
+  (descendant-visible, sibling-invisible) — Cordis's `ctx.provide`/`ctx.get`/`isolate` are
+  single-slot-per-name with no version matching and no dynamic per-id isolation; both are
+  implemented in `registry.ts`/`scope.ts`.

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@godspeedai/cognate-kernel-cordis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Cordis-backed implementation of @godspeedai/cognate-kernel-api. The only package allowed to import cordis.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GodSpeedAI/Cognate.git",
+    "directory": "packages/kernel-cordis"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@godspeedai/cognate-kernel-api": "^0.1.0",
+    "cordis": "4.0.0-rc.10"
+  }
+}

package/src/fiber.ts

@@ -0,0 +1,387 @@
+// One mounted Component occurrence. Each activation attempt is a real Cordis plugin/fiber
+// (`scope.cordisCtx.plugin(...)`); the WAITING/ACTIVATING/ACTIVE/FAILED/DEACTIVATING/DISPOSED
+// state machine, retry/backoff, activation timeout, and dependency-loss cascade are adapter-owned
+// because Cordis has none of them (ADR-0001): its own vocabulary is
+// PENDING/LOADING/ACTIVE/FAILED/DISPOSED/UNLOADING with no retry, no timeout, and no cancellation
+// of an in-flight `apply()`.
+import type { Context, Fiber } from "cordis";
+import {
+  ActivationTimeoutError,
+  CleanupError,
+  PermanentActivationError,
+  UndeclaredCapabilityError,
+} from "@godspeedai/cognate-kernel-api";
+import type {
+  CapabilityContract,
+  CapabilityHandler,
+  CapabilityLease,
+  Component,
+  ComponentHandle,
+  Disposer,
+  EffectHandle,
+  FiberContext,
+  FiberState,
+  KernelEvent,
+  Policy,
+} from "@godspeedai/cognate-kernel-api";
+import { createLease } from "./lease.ts";
+import type { CapabilityRegistry, Publication } from "./registry.ts";
+import type { ScopeImpl } from "./scope.ts";
+
+
+interface EffectEntry {
+  readonly label: string;
+  readonly disposer: Disposer;
+  disposed: boolean;
+}
+
+interface Committed {
+  readonly pub: Publication;
+  readonly unpublish: () => void;
+  readonly deactivate: () => void;
+}
+
+export class FiberUnit implements ComponentHandle {
+  readonly componentId: string;
+  readonly scopeId: string;
+  lastError: unknown;
+
+  private _state: FiberState = "WAITING";
+  private _fiberId: string | undefined;
+  private attempts = 0;
+  private terminated = false;
+  private registryUnsub: (() => void) | undefined;
+  private retryTimer: ReturnType<typeof setTimeout> | undefined;
+  private currentAttemptAbort: AbortController | undefined;
+  private teardownAbort = new AbortController();
+  private cordisFiber: (Fiber & PromiseLike<Fiber>) | undefined;
+  private effectStack: EffectEntry[] = [];
+  private pendingProvides: Array<{ contract: CapabilityContract; handler: CapabilityHandler }> = [];
+  private committed: Committed[] = [];
+  private lastCleanupError: CleanupError | undefined;
+  private readonly boundUnbind: Array<() => void> = [];
+  private readonly stateListeners = new Set<() => void>();
+
+  constructor(
+    private readonly component: Component,
+    private readonly scope: ScopeImpl,
+    private readonly registry: CapabilityRegistry,
+    private readonly policy: Policy,
+    private readonly tenant: string,
+    private readonly emit: (event: KernelEvent) => void,
+    private readonly nextId: () => string,
+  ) {
+    this.componentId = component.id;
+    this.scopeId = scope.id;
+  }
+
+  get state(): FiberState {
+    return this._state;
+  }
+
+  get fiberId(): string | undefined {
+    return this._fiberId;
+  }
+
+  start(): void {
+    this.registryUnsub = this.registry.onChange(() => this.tryActivate());
+    this.tryActivate();
+  }
+
+  waitFor(target: FiberState, timeoutMs = 2000): Promise<void> {
+    if (this._state === target) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.stateListeners.delete(listener);
+        reject(new Error(`timed out waiting for ${this.componentId} to reach ${target} (was ${this._state})`));
+      }, timeoutMs);
+      const listener = () => {
+        if (this._state !== target) return;
+        clearTimeout(timer);
+        this.stateListeners.delete(listener);
+        resolve();
+      };
+      this.stateListeners.add(listener);
+    });
+  }
+
+  async dispose(reason: string): Promise<void> {
+    await this.deactivate(reason, true);
+  }
+
+  async reset(): Promise<void> {
+    if (this._state !== "FAILED" || this.terminated) return;
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = undefined;
+    }
+    this.setState("WAITING");
+    this.tryActivate();
+  }
+
+  // --- dependency watching -------------------------------------------------
+
+  private tryActivate(): void {
+    if (this._state !== "WAITING" || this.terminated) return;
+    const requires = this.component.requires ?? {};
+    const chain = this.scope.ancestorIds();
+    const resolved: Record<string, Publication> = {};
+    for (const [key, requirement] of Object.entries(requires)) {
+      const pub = this.registry.find(requirement, chain);
+      if (!pub) return;
+      resolved[key] = pub;
+    }
+    void this.runAttempt(resolved);
+  }
+
+  // --- activation attempts --------------------------------------------------
+
+  private async runAttempt(resolved: Record<string, Publication>): Promise<void> {
+    this.attempts++;
+    this._fiberId = this.nextId();
+    this.currentAttemptAbort = new AbortController();
+    this.teardownAbort = new AbortController();
+    this.effectStack = [];
+    this.pendingProvides = [];
+    this.setState("ACTIVATING");
+
+    for (const pub of Object.values(resolved)) {
+      this.boundUnbind.push(this.registry.bind(pub, () => this.loseDependency()));
+    }
+
+    const fiberContext = this.buildFiberContext(resolved, this.currentAttemptAbort.signal);
+    // Teardown is bound to this attempt's own effect stack: a Cordis fiber abandoned by timeout may be
+    // disposed much later, after a retry has started, and must never unwind the newer attempt's effects.
+    const stack = this.effectStack;
+    const cordisFiber = this.scope.cordisCtx.plugin({
+      apply: (ctx: Context) => {
+        ctx.effect(() => () => this.teardown(stack));
+        return this.component.activate(fiberContext);
+      },
+    });
+    this.cordisFiber = cordisFiber;
+
+    // Spec §8.4: an activation that never settles fails instead of staying ACTIVATING. Cordis cannot cancel
+    // a hung apply() (its dispose() waits for it), so on timeout the adapter unwinds the attempt's effects itself.
+    const timeoutMs = this.component.activationTimeoutMs ?? 30000;
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const settled = await Promise.race([
+      cordisFiber.then(
+        () => ({ ok: true as const }),
+        (error: unknown) => ({ ok: false as const, error }),
+      ),
+      new Promise<{ ok: false; error: unknown }>((resolve) => {
+        timer = setTimeout(() => {
+          timedOut = true;
+          resolve({ ok: false, error: new ActivationTimeoutError(`activation of ${this.component.id} exceeded ${timeoutMs}ms`) });
+        }, timeoutMs);
+      }),
+    ]);
+    clearTimeout(timer);
+
+    if (timedOut) {
+      this.currentAttemptAbort.abort();
+      await this.teardown(stack);
+      cordisFiber.dispose().catch(() => {});
+      this.cordisFiber = undefined;
+    }
+
+    if (this.currentAttemptAbort.signal.aborted && !timedOut) {
+      // superseded by an explicit dispose()/loseDependency() call already driving the transition.
+      return;
+    }
+
+    if (settled.ok) {
+      for (const { contract, handler } of this.pendingProvides) this.commitProvide(contract, handler);
+      this.pendingProvides = [];
+      this.setState("ACTIVE");
+    } else {
+      this.unbindDependencies();
+      this.cordisFiber = undefined;
+      this.handleFailure(settled.error);
+    }
+  }
+
+  private commitProvide(contract: CapabilityContract, handler: CapabilityHandler): void {
+    let active = true;
+    const pub: Publication = {
+      contract,
+      providerId: this._fiberId!,
+      scopeId: this.scope.id,
+      handler,
+      teardownSignal: this.teardownAbort.signal,
+      isActive: () => active,
+    };
+    const unpublish = this.registry.publish(pub);
+    this.committed.push({ pub, unpublish, deactivate: () => (active = false) });
+    this.emit({ type: "capability.provided", capability: contract, providerId: pub.providerId, scopeId: this.scope.id });
+  }
+
+  private handleFailure(error: unknown): void {
+    this.setState("FAILED", error);
+    const retry = this.component.retry ?? { maxAttempts: 1, baseDelayMs: 0, maxDelayMs: 0 };
+    const permanent = error instanceof PermanentActivationError;
+    if (permanent || this.attempts >= retry.maxAttempts) return; // terminal FAILED until reset()
+    const backoff = Math.min(retry.maxDelayMs, retry.baseDelayMs * 2 ** (this.attempts - 1));
+    this.retryTimer = setTimeout(() => {
+      if (this.terminated) return;
+      this.setState("WAITING");
+      this.tryActivate();
+    }, backoff);
+  }
+
+  // --- teardown: the single Cordis effect every attempt registers -----------
+
+  /** Registered once via `ctx.effect()` per attempt (ADR mitigation 1 & 3): aggregates cleanup
+   * errors ourselves (Cordis reports each to its logger and never aggregates them) and withdraws
+   * every capability this occurrence published, cascading to bound dependents first so a
+   * dependent always finishes deactivating before the provider's own effects run (spec §8.4/§35). */
+  private async teardown(stack: EffectEntry[]): Promise<void> {
+    const errors: unknown[] = [];
+    // Published capabilities belong to the current occurrence only; an abandoned attempt never published.
+    const committed = stack === this.effectStack ? this.committed.splice(0) : [];
+    for (const { pub, unpublish, deactivate } of committed) {
+      deactivate();
+      await this.registry.notifyLoss(pub);
+      unpublish();
+      this.emit({ type: "capability.withdrawn", capability: pub.contract, providerId: pub.providerId, scopeId: pub.scopeId });
+    }
+    for (const entry of stack.splice(0).reverse()) {
+      if (entry.disposed) continue;
+      entry.disposed = true;
+      try {
+        await entry.disposer();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length) {
+      this.lastCleanupError = new CleanupError(this.component.id, errors);
+      this.emit({ type: "cleanup.failed", componentId: this.component.id, fiberId: this._fiberId ?? "", errors });
+    }
+  }
+
+  private unbindDependencies(): void {
+    for (const unbind of this.boundUnbind.splice(0)) unbind();
+  }
+
+  private async loseDependency(): Promise<void> {
+    if (this.terminated || (this._state !== "ACTIVE" && this._state !== "ACTIVATING")) return;
+    await this.deactivate("dependency lost", false);
+  }
+
+  private async deactivate(reason: string, terminal: boolean): Promise<void> {
+    if (this.terminated) return;
+
+    if (this._state === "WAITING" || this._state === "FAILED") {
+      if (this.retryTimer) {
+        clearTimeout(this.retryTimer);
+        this.retryTimer = undefined;
+      }
+      if (terminal) this.finalize();
+      return;
+    }
+
+    if (this._state === "ACTIVATING") {
+      this.currentAttemptAbort?.abort();
+      if (this.cordisFiber) {
+        await this.cordisFiber.dispose().catch(() => {});
+        this.cordisFiber = undefined;
+      }
+    } else if (this._state === "ACTIVE") {
+      this.setState("DEACTIVATING");
+      this.teardownAbort.abort();
+      if (this.cordisFiber) {
+        await this.cordisFiber.dispose().catch(() => {});
+        this.cordisFiber = undefined;
+      }
+    }
+
+    this.unbindDependencies();
+
+    if (terminal) {
+      this.finalize();
+      if (this.lastCleanupError) {
+        const error = this.lastCleanupError;
+        this.lastCleanupError = undefined;
+        throw error;
+      }
+    } else {
+      this._fiberId = undefined;
+      this.setState("WAITING");
+      this.tryActivate();
+    }
+  }
+
+  private finalize(): void {
+    this.terminated = true;
+    this.registryUnsub?.();
+    this.registryUnsub = undefined;
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = undefined;
+    }
+    this._fiberId = undefined;
+    this.scope.untrack(this);
+    this.setState("DISPOSED");
+  }
+
+  private setState(next: FiberState, error?: unknown): void {
+    const from = this._state;
+    this._state = next;
+    if (error !== undefined) this.lastError = error;
+    this.emit({ type: "fiber.state", componentId: this.componentId, scopeId: this.scopeId, fiberId: this._fiberId, from, to: next, error });
+    for (const listener of [...this.stateListeners]) listener();
+  }
+
+  private buildFiberContext(resolved: Record<string, Publication>, signal: AbortSignal): FiberContext {
+    const dependencies: Record<string, CapabilityLease> = {};
+    for (const [key, pub] of Object.entries(resolved)) {
+      dependencies[key] = createLease(
+        { contract: pub.contract, providerId: pub.providerId, scopeId: pub.scopeId, handler: pub.handler, teardownSignal: pub.teardownSignal },
+        this.tenant,
+        this.policy,
+        () => pub.isActive(),
+        this.emit,
+      );
+    }
+    const effectStack = this.effectStack;
+    return {
+      fiberId: this._fiberId!,
+      componentId: this.componentId,
+      scope: this.scope,
+      dependencies,
+      signal,
+      effects: {
+        register: (disposer: Disposer, label = "effect"): EffectHandle => {
+          const entry: EffectEntry = { label, disposer, disposed: false };
+          if (signal.aborted) {
+            // The attempt was abandoned (timeout or concurrent dispose): nothing will unwind it later.
+            entry.disposed = true;
+            void Promise.resolve().then(disposer).catch(() => {});
+          } else effectStack.push(entry);
+          return {
+            label,
+            get disposed() {
+              return entry.disposed;
+            },
+            dispose: async () => {
+              if (entry.disposed) return;
+              entry.disposed = true;
+              const index = effectStack.indexOf(entry);
+              if (index >= 0) effectStack.splice(index, 1);
+              await Promise.resolve(entry.disposer());
+            },
+          };
+        },
+      },
+      provide: <I, O>(contract: CapabilityContract, handler: CapabilityHandler<I, O>): void => {
+        if (!this.component.provides?.some((c) => c.id === contract.id)) {
+          throw new UndeclaredCapabilityError(`component ${this.componentId} did not declare capability ${contract.id}`);
+        }
+        this.pendingProvides.push({ contract, handler: handler as CapabilityHandler });
+      },
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+// Public surface of @godspeedai/cognate-kernel-cordis. No Cordis type crosses this boundary (spec §3.4).
+import type { KernelFactory } from "@godspeedai/cognate-kernel-api";
+import { CordisKernel } from "./kernel.ts";
+
+export const createCordisKernel: KernelFactory = (options) => new CordisKernel(options);

package/src/kernel.ts

@@ -0,0 +1,58 @@
+// Framework-owned kernel, backed by Cordis. This is the only file besides scope.ts/fiber.ts that
+// touches the `cordis` package; nothing here appears in any exported signature (spec §3.4).
+import { Context } from "cordis";
+import { ScopeClosedError } from "@godspeedai/cognate-kernel-api";
+import type { CapabilityLease, Component, ComponentHandle, Kernel, KernelEvent, KernelOptions, Requirement, Scope, Unavailable } from "@godspeedai/cognate-kernel-api";
+import { FiberUnit } from "./fiber.ts";
+import { createLease } from "./lease.ts";
+import { CapabilityRegistry } from "./registry.ts";
+import { ScopeImpl } from "./scope.ts";
+
+export class CordisKernel implements Kernel {
+  readonly root: Scope;
+  private readonly registry = new CapabilityRegistry();
+  private readonly listeners = new Set<(event: KernelEvent) => void>();
+  private readonly rootScope: ScopeImpl;
+  private readonly nextId: () => string;
+
+  constructor(private readonly options: KernelOptions) {
+    this.nextId = options.ids ?? (() => crypto.randomUUID());
+    this.rootScope = new ScopeImpl(new Context(), options.tenant, options.principal, undefined, "root");
+    this.root = this.rootScope;
+  }
+
+  async mount(component: Component, scope: Scope = this.root): Promise<ComponentHandle> {
+    const target = scope as ScopeImpl;
+    if (target.closed) throw new ScopeClosedError(`cannot mount ${component.id} into closed scope ${target.id}`);
+    const fiber = new FiberUnit(component, target, this.registry, this.options.policy, this.options.tenant, (event) => this.emit(event), this.nextId);
+    target.track(fiber);
+    fiber.start();
+    return fiber;
+  }
+
+  resolve(requirement: Requirement, scope: Scope = this.root): CapabilityLease | Unavailable {
+    const chain = (scope as ScopeImpl).ancestorIds();
+    const pub = this.registry.find(requirement, chain);
+    if (!pub) return { unavailable: true, requirement, reason: `no eligible provider for ${requirement.capability}` };
+    return createLease(
+      { contract: pub.contract, providerId: pub.providerId, scopeId: pub.scopeId, handler: pub.handler, teardownSignal: pub.teardownSignal },
+      this.options.tenant,
+      this.options.policy,
+      () => pub.isActive(),
+      (event) => this.emit(event),
+    );
+  }
+
+  observe(listener: (event: KernelEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => void this.listeners.delete(listener);
+  }
+
+  async shutdown(reason: string): Promise<void> {
+    await this.rootScope.close(reason);
+  }
+
+  private emit(event: KernelEvent): void {
+    for (const listener of [...this.listeners]) listener(event);
+  }
+}

package/src/lease.ts

@@ -0,0 +1,129 @@
+// Cordis has no first-class lease object (ADR-0001 consequence): a lease here is a Cognate-owned
+// wrapper bound to one resolved provider, revalidated on every invocation against `isValid` (the
+// fiber-owned flag flipped the instant that provider's Cordis fiber leaves ACTIVE), never against
+// Cordis's own service-availability signal directly.
+import type {
+  AuthorizationRequest,
+  CapabilityContract,
+  CapabilityHandler,
+  CapabilityLease,
+  HandlerContext,
+  InvocationContext,
+  InvocationFailure,
+  InvocationResult,
+  KernelEvent,
+  Policy,
+} from "@godspeedai/cognate-kernel-api";
+
+export interface BoundProvider {
+  readonly contract: CapabilityContract;
+  readonly providerId: string;
+  readonly scopeId: string;
+  readonly handler: CapabilityHandler;
+  /** Aborted the instant the providing fiber leaves ACTIVE (ADR mitigation: Cordis provides no cancellation signal itself). */
+  readonly teardownSignal: AbortSignal;
+}
+
+export function createLease(
+  provider: BoundProvider,
+  tenant: string,
+  policy: Policy,
+  isValid: () => boolean,
+  emit: (event: KernelEvent) => void,
+): CapabilityLease {
+  return {
+    contract: provider.contract,
+    providerId: provider.providerId,
+    get valid() {
+      return isValid();
+    },
+    invoke: (input, context) => invoke(provider, tenant, policy, isValid, emit, input, context),
+  };
+}
+
+async function invoke(
+  provider: BoundProvider,
+  tenant: string,
+  policy: Policy,
+  isValid: () => boolean,
+  emit: (event: KernelEvent) => void,
+  input: unknown,
+  context: InvocationContext,
+): Promise<InvocationResult<unknown>> {
+  if (!isValid()) return unavailable(provider.contract.id);
+
+  // Spec §32: authorization and handlers see the caller's tenant, not the kernel's.
+  const callerTenant = context.tenant ?? tenant;
+  const request: AuthorizationRequest = {
+    operation: "invoke",
+    actor: context.actor,
+    tenant: callerTenant,
+    scopeId: provider.scopeId,
+    capability: provider.contract,
+    providerId: provider.providerId,
+    correlationId: context.correlationId,
+  };
+  const decision = await policy.authorize(request);
+  emit({ type: "invocation", capability: provider.contract.id, providerId: provider.providerId, correlationId: context.correlationId, decision });
+  if (!decision.allow) return { ok: false, failure: { kind: "denied", decision } };
+  if (!isValid()) return unavailable(provider.contract.id);
+
+  const controller = new AbortController();
+  let outcome: InvocationFailure | undefined;
+  // Registered before any check can fire `abort()`, so a signal already aborted at call time
+  // (e.g. the caller aborts synchronously right after invoking) still resolves `settled`.
+  const settled = new Promise<InvocationResult<unknown>>((resolve) => {
+    controller.signal.addEventListener("abort", () => resolve({ ok: false, failure: outcome! }), { once: true });
+  });
+  const fail = (failure: InvocationFailure) => {
+    if (outcome) return;
+    outcome = failure;
+    controller.abort();
+  };
+
+  const onTeardown = () => fail({ kind: "unavailable", capability: provider.contract.id, reason: "provider torn down during invocation" });
+  provider.teardownSignal.addEventListener("abort", onTeardown, { once: true });
+  const onCancel = () => fail({ kind: "cancelled" });
+  if (context.signal?.aborted) fail({ kind: "cancelled" });
+  else context.signal?.addEventListener("abort", onCancel, { once: true });
+
+  let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+  if (context.deadline !== undefined) {
+    const remaining = Math.max(0, context.deadline - Date.now());
+    deadlineTimer = setTimeout(() => fail({ kind: "deadline_exceeded" }), remaining);
+  }
+
+  const handlerContext: HandlerContext = {
+    ...context,
+    capability: provider.contract,
+    providerId: provider.providerId,
+    decision,
+    tenant: callerTenant,
+    scopeId: provider.scopeId,
+    signal: controller.signal,
+    // Always callable: a handler never needs to guard `ctx.progress?.(...)` even when the caller
+    // did not supply a channel (spec: no-op outside a run).
+    progress: context.progress ?? (async () => {}),
+  };
+
+  const ran = (async (): Promise<InvocationResult<unknown>> => {
+    try {
+      const value = await provider.handler(input, handlerContext);
+      return { ok: true, value };
+    } catch (error) {
+      return { ok: false, failure: { kind: "failed", error } };
+    }
+  })();
+
+  try {
+    return await Promise.race([ran, settled]);
+  } finally {
+    provider.teardownSignal.removeEventListener("abort", onTeardown);
+    context.signal?.removeEventListener("abort", onCancel);
+    if (deadlineTimer) clearTimeout(deadlineTimer);
+  }
+}
+
+function unavailable(capability: string): InvocationResult<never> {
+  return { ok: false, failure: { kind: "unavailable", capability, reason: "provider is no longer active" } };
+}

package/src/registry.ts

@@ -0,0 +1,80 @@
+// Capability registry: Cognate requires multi-provider resolution keyed by capability id,
+// version and attributes (spec §8.2, isCompatible). Cordis's own service model (`ctx.provide`/
+// `ctx.get`) is a single-slot-per-name singleton with no version/attribute matching, so the
+// eligibility graph itself is adapter-owned (explicitly sanctioned: "dependency eligibility via
+// isCompatible ... implement it in the adapter"). Cordis is still used per-publication: each
+// entry here is only ever created from inside a fiber's committed `ctx.provide()` call and torn
+// down through that same fiber's Cordis effect (see fiber.ts), so the registry is a read model
+// over state whose lifetime Cordis still owns.
+import { isCompatible } from "@godspeedai/cognate-kernel-api";
+import type { CapabilityContract, CapabilityHandler, Requirement } from "@godspeedai/cognate-kernel-api";
+
+export interface Publication {
+  readonly contract: CapabilityContract;
+  readonly providerId: string;
+  readonly scopeId: string;
+  readonly handler: CapabilityHandler;
+  /** Aborted the instant the providing fiber leaves ACTIVE. */
+  readonly teardownSignal: AbortSignal;
+  isActive(): boolean;
+}
+
+type Listener = () => void;
+
+/**
+ * Scope visibility (spec §8.1): a publication is visible to the scope it was published in and
+ * every descendant, never to an ancestor or an unrelated scope. Cordis's `ctx.isolate()` only
+ * isolates one named service slot at a time and can't be driven by dynamic, per-mount capability
+ * ids, so visibility is computed here from the scope-ancestor chain the caller supplies.
+ */
+export class CapabilityRegistry {
+  private readonly byScope = new Map<string, Set<Publication>>();
+  private readonly consumers = new Map<Publication, Set<() => Promise<void>>>();
+  private readonly listeners = new Set<Listener>();
+
+  publish(pub: Publication): () => void {
+    let set = this.byScope.get(pub.scopeId);
+    if (!set) this.byScope.set(pub.scopeId, (set = new Set()));
+    set.add(pub);
+    this.consumers.set(pub, new Set());
+    this.notify();
+    return () => {
+      set!.delete(pub);
+      this.consumers.delete(pub);
+      this.notify();
+    };
+  }
+
+  /** First eligible publication visible from `scopeChain` (self, then ancestors, root last). */
+  find(requirement: Requirement, scopeChain: readonly string[]): Publication | undefined {
+    for (const scopeId of scopeChain) {
+      const set = this.byScope.get(scopeId);
+      if (!set) continue;
+      for (const pub of set) if (pub.isActive() && isCompatible(requirement, pub.contract)) return pub;
+    }
+    return undefined;
+  }
+
+  /** Bind a dependent so it is asked to react (in registration order) before its provider tears down. */
+  bind(pub: Publication, onLost: () => Promise<void>): () => void {
+    const set = this.consumers.get(pub);
+    set?.add(onLost);
+    return () => void set?.delete(onLost);
+  }
+
+  /** Notify bound dependents of `pub`'s loss, awaiting each in turn (spec: dependents deactivate before the provider). */
+  async notifyLoss(pub: Publication): Promise<void> {
+    const set = this.consumers.get(pub);
+    if (!set) return;
+    for (const onLost of [...set]) await onLost();
+  }
+
+  onChange(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => void this.listeners.delete(listener);
+  }
+
+  private notify(): void {
+    for (const listener of [...this.listeners]) listener();
+  }
+}

package/src/scope.ts

@@ -0,0 +1,86 @@
+// Cognate scopes map to Cordis contexts (ADR-0001): each Scope owns one Cordis `Context` obtained
+// via `isolate()`, giving every scope a genuine, distinct Cordis object to mount component fibers
+// onto. Capability *visibility* itself is not delegated to Cordis (see registry.ts) since Cordis's
+// isolation is per-service-name, not per-subtree, and can't be driven by dynamic capability ids
+// (spec §8.1 requires descendant-visible / sibling-invisible scoping for any capability id).
+import type { Context } from "cordis";
+import type { Principal, Scope, ScopeOptions } from "@godspeedai/cognate-kernel-api";
+import { ScopeClosedError } from "@godspeedai/cognate-kernel-api";
+
+let counter = 0;
+const nextId = () => `scope-${++counter}`;
+
+export interface Disposable {
+  dispose(reason: string): Promise<void>;
+}
+
+export class ScopeImpl implements Scope {
+  readonly id: string;
+  readonly parentId: string | undefined;
+  readonly tenant: string;
+  readonly principal: Principal;
+  readonly cordisCtx: Context;
+  private _closed = false;
+  private readonly children = new Set<ScopeImpl>();
+  private readonly mounts = new Set<Disposable>();
+
+  constructor(
+    cordisCtx: Context,
+    tenant: string,
+    principal: Principal,
+    parent: ScopeImpl | undefined,
+    id?: string,
+  ) {
+    this.cordisCtx = cordisCtx;
+    this.tenant = tenant;
+    this.principal = principal;
+    this.parentId = parent?.id;
+    this.id = id ?? nextId();
+  }
+
+  get closed(): boolean {
+    return this._closed;
+  }
+
+  /** Ancestor chain starting at this scope, root last — drives registry visibility (spec §8.1). */
+  ancestorIds(): readonly string[] {
+    const ids: string[] = [];
+    let current: ScopeImpl | undefined = this;
+    while (current) {
+      ids.push(current.id);
+      current = current.parent;
+    }
+    return ids;
+  }
+
+  private parent: ScopeImpl | undefined;
+
+  child(options?: ScopeOptions): Scope {
+    if (this._closed) throw new ScopeClosedError(`cannot create a child of closed scope ${this.id}`);
+    const id = options?.id ?? nextId();
+    const principal = options?.principal ?? this.principal;
+    const childCtx = this.cordisCtx.isolate(`cognate:scope:${id}`);
+    const scope = new ScopeImpl(childCtx, this.tenant, principal, this, id);
+    scope.parent = this;
+    this.children.add(scope);
+    return scope;
+  }
+
+  /** Track a component mounted directly in this scope so `close()` can dispose it (spec §8.1: close children first). */
+  track(mount: Disposable): void {
+    this.mounts.add(mount);
+  }
+
+  untrack(mount: Disposable): void {
+    this.mounts.delete(mount);
+  }
+
+  async close(reason: string): Promise<void> {
+    if (this._closed) return;
+    this._closed = true;
+    for (const child of [...this.children]) await child.close(reason);
+    this.children.clear();
+    for (const mount of [...this.mounts]) await mount.dispose(reason).catch(() => {});
+    this.mounts.clear();
+  }
+}