@loomwork/effect-runtime 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 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/NOTICE

@@ -0,0 +1,8 @@
+Loom
+Copyright 2026 Sushil Chhetri
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this project except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @loomwork/effect-runtime
 
-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.
+The isolation layer between a flow and the outside world. Everything a flow does that is not pure,
+a tool call, an LLM call, a human prompt, an agent-to-agent request, is an `Effect` run through an
+`EffectRuntime`, which wraps it in composable middleware (retry, rate limit, telemetry, ...) and
+applies the kernel's protection ring: capability authorization (`GrantTable`, `PolicyAuthorizer`,
+signed delegation), metering and quotas, deadlines and delivery fencing.
+
+## When to use it
+
+- You are registering the runnable side of a tool or model (`effects.register("id", effect)`), or
+  writing middleware or an authorizer.
+- Otherwise it is wired for you: `defineConfig` builds the `EffectRuntime`, and
+  `execution.registerEffects` is where an app registers its effects.
+
+## Install
+
+Not published to npm yet: `"@loomwork/effect-runtime": "workspace:*"` in this workspace, or a `link:`
+override from a sibling checkout (see [AGENTS.md](../../AGENTS.md)).
+
+## Entry points
+
+`@loomwork/effect-runtime` (single entry): `EffectRuntime`, the effect kinds `ToolEffect`, `LlmEffect`,
+`HumanEffect` (plus the lazy variant `LazyEffect`), the `Effect` / `EffectMiddleware` types, the
+authorization surface (`GrantTable`, `PolicyAuthorizer`, `DelegationAuthorizer`, `signDelegation`,
+`verifyDelegation`, `attenuateDelegation`) and `CapabilityDeniedError`.
+
+## Example
+
+```ts
+import { defineConfig } from "@loomwork/app";
+import { ToolEffect, type Effect } from "@loomwork/effect-runtime";
+
+declare const lookup: Effect; // for example: new ToolEffect(async (input) => ...)
+
+const app = defineConfig({
+  storage: { kind: "memory" },
+  flows: [],
+  execution: {
+    registerEffects: (effects) => {
+      effects.register("lookup", lookup); // the id a tool$ definition / ctx.run names
+    },
+  },
+});
+await app.close();
+void ToolEffect;
+```
+
+## Key concepts
+
+- **Middleware** is statically ordered and replay-safe: it wraps effect execution only, never the
+  fold. Reference middleware (retry, rate limit) lives in [`@loomwork/middleware`](../middleware/README.md);
+  see [ADR 0006](../../docs/adr/0006-config-and-effect-middleware.md).
+- **Capability grants (K2)**, quotas (K3), cancellation (K8) and delivery guarantees (K9) apply at
+  this seam: [kernel guide pages](../../docs/user-guide/grants-and-strict-mode.md),
+  [ADR 0021](../../docs/adr/0021-k9-effect-delivery-contract-idempotency-fencing.md).
+- Effects are `journaled` (recorded and replayed) or `ambient`; a transient facade
+  (`invokeTransient`) runs one without an execution
+  ([ADR 0066](../../docs/adr/0066-transient-effect-invocation-facade.md)).
+
+## See also
+
+- [API reference: Effects](../../docs/api-reference.org) (`@loomwork/effect-runtime`).
+- [User guide, section 3: Effects and middleware](../../docs/user-guide.md#3-effects--middleware).
+- [`@loomwork/app`](../app/README.md), [`@loomwork/agent`](../agent/README.md),
+  [`@loomwork/workflow-runtime`](../workflow-runtime/README.md).

package/dist/EffectRuntime.d.ts

@@ -0,0 +1,121 @@
+import { type EffectRuntimeOptions } from "./authz";
+import type { Effect, EffectContext, EffectMiddleware, ErrorChannelSchema, TransientInvokeOptions } from "./types";
+export declare class EffectRuntime {
+    private readonly registry;
+    private readonly middleware;
+    private readonly authorizer;
+    private readonly scheduler;
+    private readonly warmer;
+    private readonly onWarn;
+    /**
+     * @param middleware Cross-cutting middleware applied around every effect
+     * execution, in order — `middleware[0]` is outermost. The list is fixed here
+     * (static ⇒ deterministic across replay). An empty list (the default) makes
+     * `execute` behave identically to a bare effect call.
+     * @param options Optional `authorizer` (K2 protection ring), `scheduler` (M6 —
+     * route effects through it for bounded concurrency + priority), and `warmer` (M6 —
+     * advisory off-log pre-warm). All omittable; the empty case is the zero-overhead
+     * direct path with today's behaviour.
+     */
+    constructor(middleware?: readonly EffectMiddleware[], options?: EffectRuntimeOptions);
+    register(toolId: string, effect: Effect): void;
+    execute<TIn = unknown, TOut = unknown>(toolId: string, input: TIn, ctx: EffectContext): Promise<TOut>;
+    private resourceOf;
+    private runSeam;
+    /**
+     * Run a single registered effect ONCE, off the durable path — the supported
+     * façade over the already-blessed transient invocation (DE-series eval; ADR
+     * 0065 "don't make it a run until something durable happens"). It is exactly
+     * {@link execute}, but the framework owns the {@link EffectContext} instead of
+     * every caller hand-rolling one.
+     *
+     * What it does NOT do — the load-bearing guarantee (R1): nothing is written.
+     * The EffectRuntime holds no event store, no journal, and no fence, so a
+     * transient invocation produces zero envelopes, no `EXECUTION_STARTED`, no
+     * `STEP_*`, and no snapshot — structurally, not by convention. This is the
+     * sanctioned side of the ADR 0065 line: no execution, no fold, no recovery.
+     *
+     * Middleware contract (R3): the SAME statically configured effect-runtime
+     * middleware chain that a durable step's effect call runs also runs here —
+     * retry/backoff and the K2 authorizer are effect-local and remain in force.
+     * What is bypassed is everything ABOVE this layer: the workflow interpreter's
+     * journaling/durability (fold, `ExecutionJournal`, fencing, snapshots) is not
+     * EffectRuntime middleware at all, so there is nothing to opt out of.
+     *
+     * `ctx.emit` is a no-op sink (R4): an effect that emits transiently has the
+     * event DROPPED by construction — never buffered, never later flushed. Do not
+     * author a transient effect that relies on emitting durable state.
+     *
+     * The synthesized identity is throwaway: `idempotencyKey` is left unset, so do
+     * NOT rely on provider-side dedup across transient calls (they carry no stable
+     * key — a transient read path is expected to be retry-on-client).
+     *
+     * L30: `opts.as` stamps the call with an existing execution's identity (used by
+     * `ctx.decide`'s scope); it changes the claimed identity only, not R1-R5.
+     *
+     * @param opts optional {@link TransientInvokeOptions} — `signal` (cancellation,
+     * R5), `principal` (authz still enforced if wired), `label` (trace tag; without
+     * `as` also the synthetic executionId an authorizer may grant by).
+     */
+    invokeTransient<TIn = unknown, TOut = unknown>(toolId: string, input: TIn, opts?: TransientInvokeOptions): Promise<TOut>;
+    /**
+     * ADR 0119 — the per-call delta pipe between a streaming effect and the caller's
+     * sink. It owns every rule that makes a live tail safe:
+     *  - REFUSED (undefined) when any middleware `inspectsOutput` — streaming would
+     *    deliver text past a check that cannot see it; the call runs non-streamed.
+     *  - A reasoning delta (ADR 0133 D6) passes its own `deltaGuard` instances the same way and
+     *    reaches the per-call sink and the effect's configured REASONING sink, never its text
+     *    `deltaSink`.
+     *  - Each text delta passes the middleware `deltaGuard`s FIRST; a guard that throws
+     *    severs the stream and the offending delta is never delivered.
+     *  - Text is delivered as untrusted (tainted) content.
+     *  - Silent once the call settled or the call's signal aborted (an effect that
+     *    ignores the signal cannot reach a caller who moved on).
+     *  - A retry (the effect re-executed) resets guards and sends a `reset` chunk.
+     *  - The effect's own `done` chunk is held; the terminal chunk is sent by
+     *    {@link finish} after the call SUCCEEDED.
+     *  - The caller's sink throwing never fails the call (warned).
+     */
+    private deltaPipe;
+    has(toolId: string): boolean;
+    /** The registered effects, in registration order (read-only; for a composition root's boot-time checks). */
+    entries(): IterableIterator<[string, Effect]>;
+    /**
+     * Advisory pre-warm for a capability, ahead of when it's needed (latency-only,
+     * off the durable path). Spins up the registered effect's own cold resource
+     * (`Effect.warm` — e.g. a K7 child process or an LLM connection) AND fires the
+     * configured {@link Warmer} seam. Never throws: an unregistered toolId is a
+     * no-op and a warm failure is swallowed (the real call just runs cold). Does
+     * NOT authorize, meter, emit, or touch the fold — warming a capability is not
+     * invoking it (P10).
+     */
+    warm(toolId: string): void;
+    /**
+     * K9.3 — a registered effect's declared delivery semantic
+     * (`new ToolEffect(fn, { idempotent })` / `tool$({ idempotent })`). `false`
+     * means recovery must not silently re-run an attempt in an unknown state;
+     * `undefined` (undeclared, or no such effect) keeps the legacy at-least-once
+     * re-run. Pure/synchronous so the recovery decision is deterministic.
+     */
+    declaredIdempotence(toolId: string): boolean | undefined;
+    /**
+     * DE-4 — a registered effect's declared failure channels (`Effect.errors`).
+     * The kernel's registry fallback when the invoking step declares no `errors:`
+     * map of its own; `undefined` (undeclared, or no such effect) means every
+     * TypedFailure from this effect degrades to the legacy untyped failure. Pure/
+     * synchronous so the replay decision is deterministic.
+     */
+    declaredErrors(toolId: string): Record<string, ErrorChannelSchema> | undefined;
+    /**
+     * A registered effect's declared determinism-boundary mode (ADR 0073), for tooling —
+     * `@loomwork/verify` reads it to flag a `journaled` effect reached from a `ctx.decide`
+     * scope, which the transient seam refuses. `undefined` when undeclared or unregistered.
+     */
+    modeOf(toolId: string): Effect["mode"] | undefined;
+    /**
+     * The registered effect's kind, for tooling: `tool` / `llm` / `human` / `a2a` or any custom
+     * name (ADR 0115). Only `"human"` has kernel semantics (it parks).
+     */
+    kindOf(toolId: string): Effect["kind"] | undefined;
+}
+//# sourceMappingURL=EffectRuntime.d.ts.map

package/dist/EffectRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EffectRuntime.d.ts","sourceRoot":"","sources":["../src/EffectRuntime.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,oBAAoB,EAE1B,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAEV,MAAM,EACN,aAAa,EAEb,gBAAgB,EAEhB,kBAAkB,EAClB,sBAAsB,EAEvB,MAAM,SAAS,CAAC;AAEjB,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;IACzD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IAEnD;;;;;;;;;OASG;gBACS,UAAU,GAAE,SAAS,gBAAgB,EAAO,EAAE,OAAO,GAAE,oBAAyB;IAQ5F,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAWxC,OAAO,CAAC,GAAG,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,EACzC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,GAAG,EACV,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,IAAI,CAAC;IAsBhB,OAAO,CAAC,UAAU;YAgBJ,OAAO;IAgGrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,eAAe,CAAC,GAAG,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,EACjD,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,GAAG,EACV,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,IAAI,CAAC;IA6BhB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,SAAS;IAoIjB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI5B,4GAA4G;IAC5G,OAAO,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAI7C;;;;;;;;OAQG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAY1B;;;;;;OAMG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAIxD;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,SAAS;IAI9E;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,SAAS;IAIlD;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,SAAS;CAGnD"}