cordis 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 390ce9e78dbb7edfacb5cd004d46448eadd6c6ccffad5eaee9ef190c2b9a15a2
+  data.tar.gz: af955c8b180e217685481a3da9d27d9ed56bb95ce1b74c49f7f42296f1469876
+SHA512:
+  metadata.gz: 25e46a5eff3a9e977fbcaf1ccddf72ae83a3b0980d9f00aa24afac3a188fb2a284eb822955d15c64bea68b547972a552d2267b6a8c92560d28a0d72d57cc47a4
+  data.tar.gz: 95e3fa579b1a1c743aac12a4c7649b45e27df8f1882b0cb3c6ce9f7a96cd55aa052732ca12baeea66f559c02c9de8fbb0667cfd566a19fa5baad8a236505ffd8

data/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.

data/README.md

@@ -0,0 +1,201 @@
+# cordis-rb
+
+[English](#english) | [繁體中文](#繁體中文) | [日本語](#日本語)
+
+---
+
+## English
+
+> ⚠️ **Experimental** — a learning/research project, not production-ready. APIs change without notice.
+
+cordis-rb is a Ruby reimplementation of the core mechanisms of [Cordis](https://github.com/cordiverse/cordis) (a TypeScript plugin/lifecycle meta-framework), based on the paper *"A Programming Paradigm for Spatiotemporal Composability"*. It is built on the [async](https://github.com/socketry/async) gem, using Fiber-based cooperative concurrency in place of the event loop that JavaScript gets for free.
+
+### What's here so far
+
+Aligned with upstream `packages/core` (4.0 naming: `Fiber`, formerly `EffectScope`):
+
+- **Revertible effects** — `ctx.effect` applies a side effect and registers its inverse (single or multi-step); disposal is strict LIFO (Theorem 16)
+- **Plugin system** — `ctx.plugin` applies a plugin *as a revertible effect* on the parent fiber, so the whole plugin tree is one nested effect tree; loading is deferred one tick, load/unload transitions are serialized per fiber (inertia lock)
+- **Reactive coeffects** — `ctx.provide` / `ctx.inject`: consumers load when their dependencies are satisfied, reload when a provider is swapped, and are torn down *before* their provider finishes unloading
+- **Events** — `ctx.on` / `once` / `emit` / `bail` / `waterfall` (sync) and `ctx.parallel` / `serial` (async); listeners are effects, removed automatically on fiber disposal
+- **Isolation & intercept** — `ctx.isolate` puts a service name in its own realm (provides/injects no longer cross the boundary; share a realm by passing the same label); `ctx.intercept` / Hash inject configs carry per-caller config, resolved with `ctx.resolve_config`
+- **Service base class** — subclass `Cordis::Service`, declare `provide :name` (+ optional `inject`), and pass the class to `ctx.plugin`: the instance provides itself, and `#init` runs as the load body (blocking there keeps the service invisible to dependents — pending inject)
+
+```ruby
+ctx = Cordis::Context.new
+
+Sync do
+  provider = ctx.plugin(lambda { |c, _config|
+    db = Database.connect
+    c.effect { -> { db.close } } # registered before provide → runs after all dependents are gone
+    c.provide(:db, db)
+  })
+
+  ctx.inject([:db]) do |c, _config|
+    c.on('request') { |req| c.db.query(req) } # loads only once :db is active
+  end
+
+  provider.await   # wait for the deferred load
+  provider.dispose # dependents tear down first, then the provider, LIFO
+end
+```
+
+### Roadmap
+
+- [x] Revertible effects with LIFO disposal
+- [x] Plugin/fiber lifecycle (epoch + inertia state machine, via `async`)
+- [x] Reactive coeffects (`ctx.provide` / `ctx.inject`)
+- [x] Event system (`ctx.on`, waterfall included)
+- [x] Isolation & intercept (`ctx.isolate` / `ctx.intercept`)
+- [x] `Cordis::Service` base class
+- [ ] Loader / hot-reload reconciliation — maybe, later
+
+### Installation
+
+```ruby
+gem 'cordis', github: '5xRuby/cordis-rb' # not yet published to rubygems.org
+```
+
+### Development
+
+```
+bundle install && bundle exec rspec
+bundle exec ruby examples/demo.rb   # lifecycle / coeffect walkthrough
+ruby examples/webapp.rb             # the same story with Sinatra + Falcon + SQLite
+```
+
+### License
+
+[Apache-2.0](LICENSE)
+
+---
+
+## 繁體中文
+
+> ⚠️ **實驗性專案** — 練習/研究用途,不求生產可用,API 隨時會變。
+
+cordis-rb 用 Ruby 重新實作 [Cordis](https://github.com/cordiverse/cordis)(TypeScript 的 plugin/生命週期 meta-framework)的核心機制,理論基礎來自論文 *"A Programming Paradigm for Spatiotemporal Composability"*。以 [async](https://github.com/socketry/async) gem 為併發基底 —— JavaScript 有 event loop 免費提供協作式併發,Ruby 沒有對應物,這裡用 Fiber-based 的 async 補上這塊。
+
+### 目前完成
+
+對接上游 `packages/core`(4.0 命名:`Fiber`,即原本的 `EffectScope`):
+
+- **Revertible effect** — `ctx.effect` 套用副作用並登記 inverse(單步或多步);撤除嚴格 LIFO(Theorem 16)
+- **Plugin 系統** — `ctx.plugin` 把 plugin *當成一個 revertible effect* 掛在 parent fiber 上,整棵 plugin tree 就是巢狀 effect tree;載入延後一個 tick,每個 fiber 的 load/unload 由 inertia lock 序列化
+- **Reactive coeffect** — `ctx.provide` / `ctx.inject`:依賴滿足才載入、provider 被換掉就 reload、provider 卸載前依賴者先 teardown
+- **事件系統** — `ctx.on` / `once` / `emit` / `bail` / `waterfall`(同步)與 `ctx.parallel` / `serial`(非同步);listener 就是 effect,fiber 卸載時自動移除
+- **Isolation 與 intercept** — `ctx.isolate` 讓某個 service name 進入獨立 realm(provide/inject 不再跨界;傳同一個 label 可共用 realm);`ctx.intercept` 與 Hash 形式的 inject config 攜帶 per-caller 設定,用 `ctx.resolve_config` 解析
+- **Service base class** — 繼承 `Cordis::Service`、宣告 `provide :name`(可加 `inject`),把 class 直接丟給 `ctx.plugin`:instance 會 provide 自己,`#init` 就是載入本體(在裡面 block 住,service 對依賴者就不可見 —— pending inject)
+
+```ruby
+ctx = Cordis::Context.new
+
+Sync do
+  provider = ctx.plugin(lambda { |c, _config|
+    db = Database.connect
+    c.effect { -> { db.close } } # 註冊在 provide 之前 → 所有依賴者卸載後才執行
+    c.provide(:db, db)
+  })
+
+  ctx.inject([:db]) do |c, _config|
+    c.on('request') { |req| c.db.query(req) } # :db active 之後才載入
+  end
+
+  provider.await   # 等延後的載入完成
+  provider.dispose # 依賴者先卸載,再撤 provider,LIFO
+end
+```
+
+### Roadmap
+
+- [x] Revertible effect 與 LIFO 撤除
+- [x] Plugin/fiber 生命週期(epoch + inertia 狀態機,基於 `async`)
+- [x] Reactive coeffect(`ctx.provide` / `ctx.inject`)
+- [x] 事件系統(`ctx.on`,含 waterfall)
+- [x] Isolation 與 intercept(`ctx.isolate` / `ctx.intercept`)
+- [x] `Cordis::Service` base class
+- [ ] Loader / hot-reload reconciliation — 骨架穩了再說
+
+### 安裝
+
+```ruby
+gem 'cordis', github: '5xRuby/cordis-rb' # 尚未發佈到 rubygems.org
+```
+
+### 開發
+
+```
+bundle install && bundle exec rspec
+bundle exec ruby examples/demo.rb   # 生命週期 / coeffect 導覽
+ruby examples/webapp.rb             # 同一個故事,換成 Sinatra + Falcon + SQLite
+```
+
+### 授權
+
+[Apache-2.0](LICENSE)
+
+---
+
+## 日本語
+
+> ⚠️ **実験的プロジェクト** — 学習・研究目的であり、プロダクション利用は想定していません。API は予告なく変わります。
+
+cordis-rb は、[Cordis](https://github.com/cordiverse/cordis)(TypeScript 製の plugin / ライフサイクル meta-framework)のコア機構を Ruby で再実装するプロジェクトです。理論的基盤は論文 *"A Programming Paradigm for Spatiotemporal Composability"* にあります。並行処理の基盤には [async](https://github.com/socketry/async) gem を採用 —— JavaScript ではイベントループが協調的並行性を無償で提供しますが、Ruby には相当物がないため、Fiber ベースの async でその役割を担います。
+
+### 現状
+
+上流 `packages/core` に整合(4.0 命名:`Fiber`、旧 `EffectScope`):
+
+- **Revertible effect** — `ctx.effect` が副作用を適用して inverse を登録(単段・多段);巻き戻しは厳密な LIFO(Theorem 16)
+- **Plugin システム** — `ctx.plugin` は plugin を *revertible effect として* parent fiber に掛けるため、plugin ツリー全体が入れ子の effect ツリーになる;ロードは 1 tick 遅延、fiber ごとの load/unload は inertia lock で直列化
+- **Reactive coeffect** — `ctx.provide` / `ctx.inject`:依存が満たされたらロード、provider が入れ替われば reload、provider のアンロード前に依存側が先に teardown
+- **イベントシステム** — `ctx.on` / `once` / `emit` / `bail` / `waterfall`(同期)と `ctx.parallel` / `serial`(非同期);listener は effect であり、fiber の破棄時に自動で外れる
+- **Isolation と intercept** — `ctx.isolate` は service name を独立した realm に隔離(provide/inject は境界を越えない;同じ label を渡せば realm を共有);`ctx.intercept` と Hash 形式の inject config は per-caller 設定を運び、`ctx.resolve_config` で解決
+- **Service base class** — `Cordis::Service` を継承し `provide :name`(必要なら `inject` も)を宣言、class をそのまま `ctx.plugin` に渡す:instance が自身を provide し、`#init` がロード本体になる(そこで block すれば service は依存側から不可視のまま —— pending inject)
+
+```ruby
+ctx = Cordis::Context.new
+
+Sync do
+  provider = ctx.plugin(lambda { |c, _config|
+    db = Database.connect
+    c.effect { -> { db.close } } # provide より先に登録 → 依存側が全て消えた後に実行
+    c.provide(:db, db)
+  })
+
+  ctx.inject([:db]) do |c, _config|
+    c.on('request') { |req| c.db.query(req) } # :db が active になってからロード
+  end
+
+  provider.await   # 遅延ロードの完了を待つ
+  provider.dispose # 依存側が先に teardown、その後 provider、LIFO
+end
+```
+
+### Roadmap
+
+- [x] Revertible effect と LIFO 巻き戻し
+- [x] Plugin/fiber ライフサイクル(epoch + inertia ステートマシン、`async` ベース)
+- [x] Reactive coeffect(`ctx.provide` / `ctx.inject`)
+- [x] イベントシステム(`ctx.on`、waterfall 含む)
+- [x] Isolation と intercept(`ctx.isolate` / `ctx.intercept`)
+- [x] `Cordis::Service` base class
+- [ ] Loader / hot-reload reconciliation — 骨格が安定してから
+
+### インストール
+
+```ruby
+gem 'cordis', github: '5xRuby/cordis-rb' # rubygems.org には未公開
+```
+
+### 開発
+
+```
+bundle install && bundle exec rspec
+bundle exec ruby examples/demo.rb   # ライフサイクル / coeffect ウォークスルー
+ruby examples/webapp.rb             # 同じストーリーを Sinatra + Falcon + SQLite で
+```
+
+### ライセンス
+
+[Apache-2.0](LICENSE)

data/lib/cordis/context.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Cordis
+  # Thin shell: root bootstrap, service access (the paper's coeffect context), and
+  # delegation to the plugin/event entry points.
+  # Breaking change (round 2): extend now matches upstream semantics — it creates a
+  # "same root, different fiber" view of the ctx, not a new disposal scope; new scopes
+  # always come from ctx.plugin.
+  class Context
+    Impl = Struct.new(:name, :fiber, :value)
+
+    attr_reader :root, :registry, :events, :fiber, :services
+
+    def initialize
+      @root = self
+      @services = {} # isolate key => Impl (default key is the name itself)
+      @isolate = {}  # name => isolation label; absent = the shared default realm
+      @intercept = {} # name => per-caller config (copy-on-write, chain pre-merged)
+      @fiber = Fiber.new(self) # root fiber: always active, dispose = restart
+      @registry = Registry.new(self)
+      @events = Events.new(self)
+    end
+
+    # Internal: a ctx view bound to another fiber (sharing root/registry/events/services).
+    def extend(fiber: @fiber)
+      ctx = dup
+      ctx.instance_variable_set(:@fiber, fiber)
+      ctx
+    end
+
+    # A ctx view where service `name` lives in its own realm: provides/injects through
+    # this view no longer see (or are seen by) the default realm. Pass the same label
+    # to two isolate calls to share one realm between them.
+    def isolate(name, label = nil)
+      ctx = extend
+      ctx.instance_variable_set(:@isolate, @isolate.merge(name.to_sym => label || Object.new))
+      ctx
+    end
+
+    # A ctx view carrying per-caller config for service `name` (upstream ctx.intercept).
+    # Nested intercepts merge, inner overriding outer (Hash configs only; anything else replaces).
+    def intercept(name, config)
+      name = name.to_sym
+      old = @intercept[name]
+      merged = old.is_a?(Hash) && config.is_a?(Hash) ? old.merge(config) : config
+      ctx = extend
+      ctx.instance_variable_set(:@intercept, @intercept.merge(name => merged))
+      ctx
+    end
+
+    # Effective intercept config for `name` as seen from this ctx, merged over `base`
+    # (upstream Service[resolveConfig], minus the Config schema merge).
+    def resolve_config(name, base = nil)
+      config = @intercept[name.to_sym]
+      return base if config.nil?
+
+      base.is_a?(Hash) && config.is_a?(Hash) ? base.merge(config) : config
+    end
+
+    # The store key for `name` in this ctx's realm.
+    def isolate_key(name) = @isolate[name] || name
+
+    # -- effect / plugin --
+
+    def effect(label = nil, &) = @fiber.effect(label, &)
+    def plugin(plugin, config = nil) = @root.registry.plugin(self, plugin, config)
+
+    def inject(deps, &block)
+      plugin({ inject: deps, apply: block, name: 'inject' })
+    end
+
+    # -- events --
+
+    def on(name, prepend: false, &) = @root.events.register(self, name, prepend: prepend, &)
+    def once(name, prepend: false, &) = @root.events.once(self, name, prepend: prepend, &)
+    def emit(name, *) = @root.events.emit(name, *)
+    def bail(name, *) = @root.events.bail(name, *)
+    def serial(name, *) = @root.events.serial(name, *)
+    def parallel(name, *) = @root.events.parallel(name, *)
+    def waterfall(name, *, &) = @root.events.waterfall(name, *, &)
+
+    # -- service(reactive coeffect)--
+
+    # Providing a service is itself a revertible effect.
+    # Teardown ordering guarantee: remove from the store -> notify -> wait for every
+    # dependent to finish unloading -> only then delete the provider's self-visible entry
+    # (so dependents' disposers can still reach the service during their own teardown).
+    def provide(name, value = nil)
+      name = name.to_sym
+      key = isolate_key(name)
+      owner = @fiber
+      @fiber.effect("ctx.provide(#{name.inspect})") do
+        raise ServiceError, "service #{name.inspect} has already been registered" if @root.services.key?(key)
+
+        impl = Impl.new(name, owner, value)
+        @root.services[key] = impl
+        owner.store[name] = impl # immediately visible to the provider itself
+        owner.provided[name] = key
+        @root.notify({ name => key }) if owner.state == :active
+        lambda do
+          @root.services.delete(key)
+          dependents = @root.notify({ name => key })
+          dependents.each do |dep|
+            dep.await
+          rescue StandardError
+            nil # allSettled semantics: one dependent failing to unload never blocks the rest
+          end
+          owner.store&.delete(name)
+          owner.provided.delete(name)
+        end
+      end
+    end
+
+    # Strict: the provider fiber must be ACTIVE to be visible (a service whose provider
+    # is still loading is invisible to dependents).
+    def get(name)
+      impl = @root.services[isolate_key(name.to_sym)]
+      return nil unless impl && impl.fiber.state == :active
+
+      impl.value
+    end
+
+    def set(name, value)
+      name = name.to_sym
+      impl = @root.services[isolate_key(name)]
+      raise ServiceError, %(cannot set property "#{name}" without provide) unless impl
+      raise ServiceError, %(cannot set property "#{name}" in multiple fibers) unless impl.fiber.equal?(@fiber)
+
+      impl.value = value
+    end
+
+    # Dependency-graph update (fully synchronous): linear scan over all fibers,
+    # re-checking satisfaction and recomputing epochs. Only fibers whose ctx resolves
+    # the name to the same isolate key are touched. Takes { name => key } pairs and
+    # returns the touched fibers (provide's teardown uses the list to wait for dependents).
+    def notify(pairs)
+      touched = []
+      @registry.runtimes.each do |runtime|
+        runtime.fibers.each do |fib|
+          hits = pairs.select { |n, key| fib.inject.key?(n) && fib.ctx.isolate_key(n) == key }
+          next if hits.empty?
+
+          hits.each_key { |n| fib.check_impl(n) }
+          fib.refresh
+          touched << fib
+        end
+      end
+      pairs.each_key { |n| @events.emit('internal/service', n) }
+      touched
+    end
+
+    # Service access: walk the fiber parent chain looking at snapshots
+    # (error messages match upstream).
+    def method_missing(name, *args, &block)
+      return super unless args.empty? && block.nil?
+
+      resolve_service(name)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @root.services.key?(isolate_key(name)) || super
+    end
+
+    private
+
+    def resolve_service(name)
+      key = isolate_key(name)
+      fib = @fiber
+      loop do
+        if fib.store
+          impl = fib.store[name]
+          # a service this fiber *provides* is only visible from the same realm
+          # (stricter than upstream, whose walk is name-keyed at the terminal fiber)
+          return impl.value if impl && (!fib.provided.key?(name) || fib.provided[name] == key)
+        end
+        raise ServiceError, %(cannot get required service "#{name}" in inactive context) if fib.inject.key?(name)
+        # stop at root, or when walking up would cross an isolation boundary
+        if fib.root? || fib.parent_ctx.isolate_key(name) != key
+          raise ServiceError, %(cannot get property "#{name}" without inject)
+        end
+
+        fib = fib.parent_fiber
+      end
+    end
+  end
+end

data/lib/cordis/events.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'async'
+
+module Cordis
+  # Event system (upstream 4.0's EventsService): registering a listener is itself a
+  # fiber effect, so listeners are removed automatically when the fiber unloads.
+  # emit/bail/waterfall are synchronous; parallel requires a reactor.
+  class Events
+    Hook = Struct.new(:ctx, :callback)
+
+    attr_reader :hooks
+
+    def initialize(ctx)
+      @ctx = ctx
+      @hooks = Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def register(ctx, name, prepend: false, &callback)
+      list = @hooks[name]
+      hook = Hook.new(ctx, callback)
+      ctx.fiber.effect("ctx.on(#{name.inspect})") do
+        prepend ? list.unshift(hook) : list.push(hook)
+        -> { list.reject! { |h| h.equal?(hook) } }
+      end
+    end
+
+    def once(ctx, name, prepend: false, &callback)
+      dispose = register(ctx, name, prepend: prepend) do |*args|
+        dispose.call
+        callback.call(*args)
+      end
+    end
+
+    # Synchronous fan-out; return values ignored; listener exceptions propagate (matches upstream).
+    def emit(name, *)
+      @hooks[name].dup.each { |hook| hook.callback.call(*) }
+      nil
+    end
+
+    # Sequential calls; returns the first non-nil/false result.
+    # serial is the same semantics named for async listeners: Ruby async is blocking-style,
+    # a listener just blocks, so the two share one implementation.
+    def bail(name, *)
+      @hooks[name].dup.each do |hook|
+        result = hook.callback.call(*)
+        return result if bailed?(result)
+      end
+      nil
+    end
+    alias serial bail
+
+    # Middleware chain: each listener receives an extra next (callable); not calling
+    # next stops the chain; the fallback block runs only when every listener passed through.
+    def waterfall(name, *, &fallback)
+      chain = @hooks[name].dup
+      index = -1
+      step = nil
+      step = lambda do |*current|
+        index += 1
+        if index < chain.size
+          chain[index].callback.call(*current, step)
+        elsif fallback
+          fallback.call(*current)
+        end
+      end
+      step.call(*)
+    end
+
+    # Call all listeners concurrently without short-circuiting: exceptions are collected
+    # into an AggregateError after everything ran (requires Sync/Async).
+    def parallel(name, *)
+      parent = Async::Task.current
+      tasks = @hooks[name].dup.map do |hook|
+        parent.async { hook.callback.call(*) }
+      end
+      errors = []
+      tasks.each do |task|
+        task.wait
+      rescue StandardError => e
+        errors << e
+      end
+      raise AggregateError, errors unless errors.empty?
+
+      nil
+    end
+
+    private
+
+    def bailed?(result) = !result.nil? && result != false
+  end
+end

data/lib/cordis/fiber.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require 'async'
+
+module Cordis
+  # Fiber (upstream 4.0's new name for EffectScope): the lifecycle unit of a plugin,
+  # and also the collector of revertible effects (the paper's phi accumulator).
+  # Note: the clash with Ruby core's ::Fiber is deliberate, to match upstream naming;
+  # Cordis never uses core Fiber directly.
+  class Fiber
+    INACTIVE = :__inactive__
+
+    Entry = Struct.new(:disposers, :label)
+
+    attr_reader :uid, :ctx, :runtime, :inject, :store, :config, :error, :provided, :parent_fiber, :parent_ctx,
+                :state
+
+    def initialize(parent_ctx, config: nil, inject: {}, runtime: nil)
+      @config = config
+      @inject = inject
+      @runtime = runtime
+      @disposables = []
+      @provided = {} # name => isolate key (for boundary-crossing notify on state change)
+      @internal_store = {} # currently satisfied dependencies (name => Impl), continuously updated
+      @store = nil         # snapshot taken while loading; nil means unloaded
+      @current_epoch = INACTIVE
+      @target_epoch = INACTIVE
+      @inertia = nil       # in-flight load/unload transition task
+      @error = nil
+      @state = :pending
+
+      if runtime.nil? # root fiber
+        @uid = 0
+        @ctx = parent_ctx
+        @parent_fiber = nil
+        @current_epoch = @target_epoch = ''
+        @store = {}
+        @state = :active
+        return
+      end
+
+      @uid = parent_ctx.root.registry.next_uid
+      @parent_fiber = parent_ctx.fiber
+      @parent_ctx = parent_ctx
+      @ctx = parent_ctx.extend(fiber: self)
+      # inject with a Hash config doubles as an intercept entry on the plugin's ctx
+      # (mirrors upstream fiber.ts:139)
+      inject.each { |dep, cfg| @ctx = @ctx.intercept(dep, cfg) if cfg.is_a?(Hash) }
+      runtime.fibers << self
+      @ctx.events.emit('internal/plugin', self)
+      inject.each_key { |name| check_impl(name) }
+      # a plugin is itself a revertible effect on the parent fiber (mirrors upstream fiber.ts:170)
+      @entry = parent_ctx.fiber.effect('ctx.plugin()') do
+        refresh
+        -> { terminate }
+      end
+    end
+
+    def root? = @runtime.nil?
+    def disposed? = @uid.nil?
+
+    def name
+      return 'root' if root?
+
+      @runtime.name || 'plugin'
+    end
+
+    # Apply a side effect and collect its inverse. The block returns: nil (nothing),
+    # a callable (single disposer), or an Array/Enumerator of callables (multi-step
+    # disposers, reverted in reverse order — upstream's function* effects).
+    # If setup raises midway, already-collected disposers are rolled back in reverse, then re-raised.
+    def effect(label = nil, &block)
+      assert_active
+      disposers = collect_disposers(block, rollback: true)
+      entry = Entry.new(disposers, label)
+      @disposables << entry
+      lambda do
+        next unless @disposables.reject! { |e| e.equal?(entry) }
+
+        entry.disposers.reverse_each(&:call)
+      end
+    end
+
+    def assert_active
+      return if @store && %i[loading active].include?(@state)
+
+      raise InactiveEffectError, 'cannot create effect on inactive context'
+    end
+
+    # Wait for all in-flight transitions to finish (while, not if: transitions chain).
+    def await
+      while (task = @inertia)
+        task.wait
+      end
+      raise @error if @error
+
+      self
+    end
+
+    def dispose
+      return restart if root?
+
+      @entry.call
+      nil
+    end
+
+    def restart
+      set_epoch(INACTIVE)
+      await # wait for the unload first (refreshing right away would set the target back
+      # to the original epoch and coalesce the unload intent away)
+      refresh
+      await
+    end
+
+    def update(config)
+      @config = config
+      restart
+    end
+
+    # -- coeffect machinery (dependency-graph updates are fully synchronous;
+    #    only load/unload execution is async) --
+
+    def check_impl(name)
+      impl = @ctx.root.services[@ctx.isolate_key(name)]
+      if impl && impl.fiber.state == :active
+        @internal_store[name] = impl
+      else
+        @internal_store.delete(name)
+      end
+    end
+
+    def refresh
+      epoch = ''
+      @inject.each_key do |name|
+        impl = @internal_store[name]
+        if impl.nil?
+          epoch = INACTIVE
+          break
+        end
+        epoch = "#{epoch}:#{impl.fiber.uid}"
+      end
+      set_epoch(epoch)
+    end
+
+    private
+
+    def collect_disposers(block, rollback: false)
+      disposers = []
+      result = block.call
+      case result
+      when nil then nil
+      when Array, Enumerator
+        # collect incrementally (never force the whole enumeration first): if it raises
+        # midway, only disposers yielded so far can be rolled back
+        result.each do |disposer|
+          validate_disposer(disposer)
+          disposers << disposer
+        end
+      else
+        validate_disposer(result)
+        disposers << result
+      end
+      disposers
+    rescue StandardError
+      disposers.reverse_each { |d| safe_call(d) } if rollback
+      raise
+    end
+
+    def validate_disposer(disposer)
+      return if disposer.respond_to?(:call)
+
+      raise TypeError, "invalid effect: disposer must be callable, got #{disposer.inspect}"
+    end
+
+    def safe_call(disposer)
+      disposer.call
+    rescue StandardError => e
+      warn "Cordis: error while disposing (#{name}): #{e.class}: #{e.message}"
+    end
+
+    def set_epoch(epoch)
+      return if epoch == @target_epoch
+
+      @target_epoch = epoch
+      return if @inertia # transition in flight: just record the intent; re-checked on completion
+
+      start_transition
+    end
+
+    # Inertia lock: at most one transition task per fiber at a time; on completion the
+    # target epoch is re-checked and, if it changed, the next transition is chained.
+    def start_transition
+      task = Async::Task.current # raises outside a reactor (plugin/provide require Sync/Async)
+      set_state(@current_epoch == INACTIVE ? :loading : :unloading)
+      @inertia = task.async do
+        Async::Task.current.yield # defer by one tick (upstream's await Promise.resolve())
+        loop do
+          if @current_epoch == INACTIVE
+            break if @target_epoch == INACTIVE
+
+            do_load
+          else
+            break if @target_epoch == @current_epoch
+
+            do_unload
+          end
+        end
+        @inertia = nil
+        set_state(resting_state)
+      end
+    end
+
+    def do_load
+      goal = @target_epoch
+      @error = nil
+      @store = @internal_store.dup # snapshot: a loading plugin sees a frozen view of its deps
+      set_state(:loading)
+      begin
+        result = @runtime.callback.call(@ctx, @config) unless root?
+        # ponytail: a plugin return value only counts as a disposer when callable
+        # (upstream _execute is stricter and raises TypeError)
+        @disposables << Entry.new([result], 'plugin:return') if result.respond_to?(:call)
+      rescue StandardError => e
+        @error = e
+        warn "Cordis: plugin #{name} failed to load: #{e.class}: #{e.message}"
+      end
+      @current_epoch = goal
+    end
+
+    def do_unload
+      set_state(:unloading)
+      # ponytail: strict LIFO sequential disposal, each rescued individually
+      # (upstream starts in LIFO order but finishes concurrently)
+      until @disposables.empty?
+        entry = @disposables.pop
+        entry.disposers.reverse_each { |d| safe_call(d) }
+      end
+      @store = nil
+      @error = nil
+      @current_epoch = INACTIVE
+    end
+
+    def resting_state
+      return :disposed if disposed?
+      return :failed if @error
+
+      @current_epoch == INACTIVE ? :pending : :active
+    end
+
+    def set_state(new_state)
+      return if new_state == @state
+
+      old = @state
+      @state = new_state
+      @ctx.events.emit('internal/status', self, old)
+      # crossing the ACTIVE boundary changes the visibility of services this fiber
+      # provides -> notify dependents
+      crossed = (old == :active) ^ (new_state == :active)
+      @ctx.root.notify(@provided.dup) if crossed && !@provided.empty?
+    end
+
+    # Called by the parent's effect disposer (or manually via #dispose)
+    def terminate
+      set_epoch(INACTIVE)
+      begin
+        await
+      rescue StandardError
+        nil # disposing a FAILED fiber never raises (the error was already warned at load time)
+      end
+      @uid = nil
+      set_state(:disposed)
+      @ctx.root.registry.remove(self)
+      @ctx.events.emit('internal/plugin', self)
+    end
+  end
+end

data/lib/cordis/registry.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Cordis
+  # Plugin registry: keyed by the resolved callback — one Runtime per callback,
+  # applying the same plugin N times = N fibers under one Runtime.
+  class Registry
+    Runtime = Struct.new(:name, :callback, :fibers, :key)
+
+    def initialize(ctx)
+      @ctx = ctx
+      @store = {}
+      @counter = 0
+    end
+
+    def next_uid = (@counter += 1)
+    def size = @store.size
+    def runtimes = @store.values
+
+    # Entry point for ctx.plugin. Plugin shapes: a callable, { apply:, inject:, name: },
+    # or a Class (instantiated at load time; see Cordis::Service).
+    # Returns the fiber synchronously; the actual apply is deferred one tick
+    # (must be called inside Sync/Async).
+    def plugin(ctx, plugin, config = nil)
+      key, callback, inject, name = resolve(plugin)
+      ctx.fiber.assert_active
+      runtime = @store[key] ||= Runtime.new(name, callback, [], key)
+      Fiber.new(ctx, config: config, inject: inject, runtime: runtime)
+    end
+
+    def remove(fiber)
+      runtime = fiber.runtime
+      runtime.fibers.reject! { |f| f.equal?(fiber) }
+      @store.delete(runtime.key) if runtime.fibers.empty?
+    end
+
+    private
+
+    def resolve(plugin)
+      case plugin
+      when Hash
+        apply = plugin[:apply]
+        raise ArgumentError, "invalid plugin: apply must be callable, got #{apply.inspect}" \
+          unless apply.respond_to?(:call)
+
+        [apply, apply, normalize_inject(plugin[:inject]), plugin[:name]]
+      when Class
+        # class plugin (upstream isConstructor): instantiated during load; a Service
+        # subclass provides itself in #initialize, then #init runs as the load body
+        inject = plugin.respond_to?(:inject) ? plugin.inject : nil
+        callback = lambda do |c, config|
+          instance = plugin.new(c, config)
+          instance.init if instance.respond_to?(:init)
+        end
+        [plugin, callback, normalize_inject(inject), plugin.name]
+      else
+        raise ArgumentError, "invalid plugin: #{plugin.inspect}" unless plugin.respond_to?(:call)
+
+        [plugin, plugin, {}, nil]
+      end
+    end
+
+    def normalize_inject(inject)
+      case inject
+      when nil then {}
+      when Array then inject.to_h { |dep| [dep.to_sym, true] }
+      when Hash then inject.transform_keys(&:to_sym)
+      else raise ArgumentError, "invalid inject: #{inject.inspect}"
+      end
+    end
+  end
+end

data/lib/cordis/service.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Cordis
+  # Class-style plugin that provides itself as a service (upstream Service base class).
+  # Declare the name with `provide :foo` and dependencies with `inject`; the instance
+  # becomes the service value, and #init (if defined) runs as the plugin load body.
+  #
+  #   class AuditLog < Cordis::Service
+  #     provide :audit
+  #     inject :db
+  #     def init = ctx.on('request') { ... }
+  #   end
+  #   ctx.plugin(AuditLog)
+  class Service
+    class << self
+      # DSL setter and registry-facing getter in one (upstream `static provide`).
+      def provide(name = nil)
+        @service_name = name.to_sym if name
+        @service_name
+      end
+
+      # `inject :foo, :bar` or `inject foo: { config }` (upstream `static inject`);
+      # called with no arguments it returns the accumulated map for the registry.
+      def inject(*names, **configs)
+        @inject ||= {}
+        names.each { |dep| @inject[dep.to_sym] = true }
+        configs.each { |dep, cfg| @inject[dep.to_sym] = cfg }
+        @inject
+      end
+    end
+
+    attr_reader :ctx, :name, :config
+
+    def initialize(ctx, config = nil)
+      name = self.class.provide
+      raise ArgumentError, "#{self.class} must declare `provide :name`" unless name
+
+      @ctx = ctx
+      @config = config
+      @name = name
+      ctx.provide(name, self)
+    end
+
+    # Load-time hook: runs while the fiber is still loading, so blocking here keeps
+    # the service invisible to dependents (upstream's "pending inject" via Service.init).
+    # A callable return value is collected as a disposer.
+    def init; end
+  end
+end

data/lib/cordis/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Cordis
+  VERSION = '0.1.0'
+end

data/lib/cordis.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Cordis
+  class Error < StandardError; end
+
+  # Raised when creating an effect / plugin / listener on a non-active context
+  class InactiveEffectError < Error; end
+
+  # Service access violations (without inject / inactive context / duplicate provide / bad set)
+  class ServiceError < Error; end
+
+  # Aggregated errors from parallel (Ruby has no built-in AggregateError)
+  class AggregateError < Error
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+      super("#{errors.size} error(s): #{errors.map(&:message).join('; ')}")
+    end
+  end
+end
+
+require_relative 'cordis/version'
+require_relative 'cordis/fiber'
+require_relative 'cordis/registry'
+require_relative 'cordis/events'
+require_relative 'cordis/context'
+require_relative 'cordis/service'

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: cordis
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ryudoawaru
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.35'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.35'
+description: Revertible effects with LIFO disposal, a plugin/fiber lifecycle state
+  machine, reactive coeffects (service provide/inject), events, and service isolation
+  — the core mechanisms of Cordis (cordiverse/cordis), reimplemented on the async
+  gem. Based on the paper "A Programming Paradigm for Spatiotemporal Composability".
+email:
+- ryudoawaru@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/cordis.rb
+- lib/cordis/context.rb
+- lib/cordis/events.rb
+- lib/cordis/fiber.rb
+- lib/cordis/registry.rb
+- lib/cordis/service.rb
+- lib/cordis/version.rb
+homepage: https://github.com/5xRuby/cordis-rb
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/5xRuby/cordis-rb
+  changelog_uri: https://github.com/5xRuby/cordis-rb/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: A Ruby port of the Cordis plugin/lifecycle meta-framework
+test_files: []