textus 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c72c516279aeb0df734da1a72dd89fd033ebbed2e891444b71015e04fab73e75
-  data.tar.gz: a1075b8990c6c1749eb03f5042c1e5bd590456307cf9b3e1a9de9c33dcc0a862
+  metadata.gz: 98c2ce5525bbf9c05ebdb5eeaacde8e208253ee878d7d0722ff192435168f69f
+  data.tar.gz: c16cd5657396884c646331912d988838e0f8ed2002fc76d47cc54383dc434f19
 SHA512:
-  metadata.gz: 2218efa63e1ae6f246af3341bbb27e713a71a381a4aa84d15d46e687b8585c3bb5f992d75456c6112c960fec8a286c3cb7e6e672af04db0d2657811b45627ffb
-  data.tar.gz: 98ec77bf76fe14c850470e9dee3aebe55bba44ae6d4aa6303951eab2d697f2eed4d8d2d44278615e7e80873704d41dcd46109f244414ca2d16c7a4c4a7c12e2a
+  metadata.gz: 7478459f9672474c32f37b59a7134309cf12f6a7455a808c24b6ac717820ff8c8aad5a5187a6dbe5e0c73f98c04296ce95eff2cac8ea75144f559df8cea3fe80
+  data.tar.gz: '08a29e9090f6558a010009e3562a7ec8d6ddf73454bb09b10b5aeaf3def24d9d11905078d62807b8e1f0936b00889a66df8c55d68b7dfc411addd90e60ae1a93'

data/CHANGELOG.md

@@ -10,6 +10,21 @@ is additive within a major; a new major would change the wire string.
 
 ## [Unreleased]
 
+## 0.4.0 — Extension API redesign (breaking)
+
+- **Breaking:** `Textus.fetcher` removed. Use `Textus.action` instead. The block signature changes from `|config:, store:|` to `|config:, store:, args:|`.
+- **Breaking:** Manifest field `source.fetcher` renamed to `source.action`. Legacy field is rejected with a migration error.
+- **Breaking:** CLI flag `textus put --fetcher=NAME` renamed to `textus put --action=NAME`.
+- **Breaking:** `BuiltinFetchers` module renamed to `BuiltinActions`.
+- **Breaking:** Synthesized frontmatter key `fetched_with` renamed to `actioned_with` on `put --action`.
+- **New:** `Textus.action` works in three invocation modes — intake refresh, the new `textus action NAME` verb, and `put --action`. See SPEC §5.11.
+- **New:** `Textus.doctor_check(:name) { |store:| ... }` primitive; contributed checks merge into the doctor report.
+- **New:** `textus action NAME [--key=val ...] [--as=ROLE]` CLI verb for invoking actions in verb mode.
+- **New:** `StoreView` gains a writable mode (`writable: true, as: ROLE`); intake and verb-mode actions receive a writable view bound to the calling role.
+- **New:** `extensions list` enumerates actions and doctor_checks.
+
+Migration: in every `.textus/extensions/*.rb`, rename `Textus.fetcher(:x)` to `Textus.action(:x)` and add `args:` to the block signature. In every manifest, rename `source.fetcher:` to `source.action:`. In CI/scripts using `textus put --fetcher=`, switch to `--action=`.
+
 ## [0.3.0] — 2026-05-20 — Configurable store root
 
 ### Added

data/README.md

@@ -45,12 +45,12 @@ You get `.textus/` with all five zone directories, baseline schemas, an empty au
   audit.log           # append-only NDJSON, every write
   schemas/            # YAML field shapes per entry family
   templates/          # mustache templates for derived entries
-  extensions/         # one .rb per fetcher / reducer / hook
+  extensions/         # one .rb per action / reducer / hook / doctor_check
   sentinels/          # publish bookkeeping
   zones/
     canon/            # human-only — identity, voice, decisions
     working/          # human / ai / script — day-to-day catalog
-    intake/           # script — declared external inputs (fetchers)
+    intake/           # script — declared external inputs (actions)
     pending/          # ai + human — proposals awaiting accept
     derived/          # build only — computed outputs
 ```
@@ -67,7 +67,7 @@ echo '{"frontmatter":{"name":"bob","org":"acme"},"body":"hi\n"}' \
 textus stale --zone=derived --format=json
 ```
 
-For the full shape — Claude plugin with agents, skills, commands, pending walkthrough, intake fetcher — see [`examples/claude-plugin/`](examples/claude-plugin/).
+For the full shape — Claude plugin with agents, skills, commands, pending walkthrough, intake action — see [`examples/claude-plugin/`](examples/claude-plugin/).
 
 ## What 0.2 ships
 
@@ -98,13 +98,14 @@ All verbs accept `--format=json` and return the envelope defined in SPEC §8. Wr
 | `deps K` / `rdeps K` | Forward / reverse projection dependencies |
 | `published` | List `publish_to:` targets and their backing keys |
 | `validate-all` | Validate every entry against its schema |
-| `extensions list [--kind=K]` | Registered fetchers, reducers, declared hooks |
+| `extensions list [--kind=K]` | Registered actions, reducers, hooks, doctor_checks |
 
 **Write:**
 
 | Verb | Role |
 |---|---|
-| `put K --stdin --as=R [--fetcher=NAME]` | per zone |
+| `put K --stdin --as=R [--action=NAME]` | per zone |
+| `action NAME [--key=val] [--as=R]` | per zone written (invoke a registered action) |
 | `delete K --if-etag=E --as=R` | per zone |
 | `refresh K --as=script` | per zone (typically `script`) |
 | `mv old new --as=R [--dry-run]` | per zone (same-zone moves; uid preserved) |
@@ -133,7 +134,7 @@ All verbs accept `--format=json` and return the envelope defined in SPEC §8. Wr
 |---|---|---|
 | `canon` | `[human]` | Identity, voice, decisions — slow-changing |
 | `working` | `[human, ai, script]` | Active project state |
-| `intake` | `[script]` | Declared external inputs (fetchers) |
+| `intake` | `[script]` | Declared external inputs (actions) |
 | `pending` | `[ai, human]` | AI proposals; humans run `textus accept` to apply |
 | `derived` | `[build]` | Computed outputs from `textus build` |
 
@@ -147,17 +148,18 @@ Derived entries declare a `projection:` (`select`, `pluck`, `sort_by`, `limit`,
 
 ## Extensions
 
-Three DSL verbs, registered in `.textus/extensions/*.rb`. Each `Store` gets its own registry — no global state.
+Four DSL verbs, registered in `.textus/extensions/*.rb`. Each `Store` gets its own registry — no global state.
 
-- **`Textus.fetcher(:name) do |config:, store:|`** — pulls data into an intake entry. Returns `{frontmatter:, body:}`, `{content:}` (for json/yaml entries), or `{body:}` (raw). The store normalizes all three shapes. Configured via `source.fetcher` in the manifest. Five built-ins ship: `json`, `csv`, `markdown-links`, `ical-events`, `rss`.
+- **`Textus.action(:name) do |config:, store:, args:|`** — runs in three invocation modes (intake refresh, `textus action` verb, `put --action`). Returns `{frontmatter:, body:}`, `{content:}`, or `{body:}` when its return is consumed (intake and put-fetch); writes via `store.put` for side-effectful work (verb mode). The store normalizes all three return shapes. Configured via `source.action` in the manifest for intake. Five built-ins ship: `json`, `csv`, `markdown-links`, `ical-events`, `rss`.
 - **`Textus.reducer(:name) do |rows:, config:|`** — shapes rows in a derived projection. Pure function. Configured via `projection.reducer`. May return an Array (templated builds) or a Hash (templateless json/yaml).
 - **`Textus.hook(:event, :name) do |kwargs|`** — fires on `:put`, `:delete`, `:refresh`, `:build`, or `:accept`. In-process; 2 s timeout per hook; failures land in the audit log as `event_error` rows.
+- **`Textus.doctor_check(:name) do |store:|`** — contributes whole-tree validators to `textus doctor`. Returns an array of issue hashes `{code, level, subject, message, fix}` that merge into the doctor report. Timeouts and exceptions surface as `doctor_check.*` issues; they do not abort the doctor run.
 
 Schemas (`.textus/schemas/<name>.yaml`) declare field shapes, per-field `maintained_by:` ownership, and an `evolution:` block (`added_in`, `deprecated_at`, `migrate_from`). Full contract in SPEC §5.8 and §5.11.
 
 ## Examples
 
-[`examples/claude-plugin/`](examples/claude-plugin/) — a Claude Code plugin (`voice-tools`) whose entire content surface — agents, skills, commands, `CLAUDE.md`, `plugin.json`, `marketplace.json` — is textus-managed. Demonstrates per-entry formats, `publish_each`, intake fetchers, in-process reducers and hooks, the AI-propose / human-accept loop, and the `inject_intro:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
+[`examples/claude-plugin/`](examples/claude-plugin/) — a Claude Code plugin (`voice-tools`) whose entire content surface — agents, skills, commands, `CLAUDE.md`, `plugin.json`, `marketplace.json` — is textus-managed. Demonstrates per-entry formats, `publish_each`, intake actions, in-process reducers and hooks, the AI-propose / human-accept loop, and the `inject_intro:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
 
 ## Tests
 

data/SPEC.md

@@ -46,7 +46,7 @@ textus is organized as five composable layers. Each layer has a single responsib
 - Not a sync protocol. Single-writer per file, ETag-checked.
 - Not a transport. Spawn the CLI or wrap it in MCP/HTTP downstream.
 - Not a UI. Filesystem + CLI. Viewers ship elsewhere.
-- Not a fetcher. textus declares sources; external runners fetch them.
+- Not a fetcher. textus declares sources; external runners invoke actions to materialize them.
 - Not an executor. textus computes pure projections but never spawns shell commands.
 
 ## 3. Storage layout
@@ -250,38 +250,38 @@ A sentinel is written for each published file at `<store_root>/sentinels/<target
 
 **Per-leaf publishing.** A nested entry MAY declare `publish_each:` instead of `publish_to:` (see §4). When the build runs, every leaf reachable under the nested entry is byte-copied to the path produced by substituting `{leaf}` / `{basename}` / `{key}` / `{ext}` in the template, with a sentinel written under `<store_root>/sentinels/` at the mirrored target path. The build envelope grows a `published_leaves` array — one row per leaf, with `key`, `source`, and `target` — alongside the existing `built` array. Targets that would resolve outside the repo root are refused.
 
-### 5.4 Intake (declared, refreshed via registered fetcher)
+### 5.4 Intake (declared, refreshed via registered action)
 
-Intake entries declare an external source by naming a **fetcher** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: a fetcher only runs when explicitly invoked by `textus refresh KEY --as=script`. The declaration is data only:
+Intake entries declare an external source by naming an **action** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: an action only runs in intake mode when explicitly invoked by `textus refresh KEY --as=script`. The declaration is data only:
 
 ```yaml
 - key: intake.calendar.events
   zone: intake
   source:
-    fetcher: ical-events
+    action: ical-events
     config:
       url: "https://calendar.google.com/.../basic.ics"
     ttl: 6h
 ```
 
-`fetcher` names a registered fetcher; `config` is an opaque hash handed to the fetcher; `ttl` is the staleness budget. Implementations MUST reject legacy `source.from` and `source.parse` with a clear usage error.
+`action` names a registered action; `config` is an opaque hash handed to the action; `ttl` is the staleness budget. Implementations MUST reject legacy `source.from`, `source.parse`, and `source.fetcher` with a clear usage error.
 
-**Fetcher contract.** A fetcher is registered via `Textus.fetcher(:name) do |config:, store:| ... end` and MUST return one of three shapes, all normalized by the store into its internal `{frontmatter, body, content}` representation (§5.12):
+**Action contract (intake mode).** An action is registered via `Textus.action(:name) do |config:, store:, args:| ... end`. In intake mode the action MUST return one of three shapes, all normalized by the store into its internal `{frontmatter, body, content}` representation (§5.12):
 
-- `{ frontmatter:, body: }` — markdown-friendly (current shape).
+- `{ frontmatter:, body: }` — markdown-friendly.
 - `{ content: }` — for `format: json|yaml` entries; the parsed object becomes the entry's content.
 - `{ body: }` — raw bytes for `text` or for any format that prefers verbatim writes; the store re-parses and validates per `format:`.
 
-The `store:` argument is a read-only `Textus::StoreView` (§5.11). Every fetcher call is wrapped in `Timeout.timeout(2)`; exceptions and timeouts surface as `usage` errors that abort the refresh.
+The `store:` argument is a writable `Textus::StoreView` (§5.11) bound to the calling role; the `args:` argument is `{}` in intake mode (it carries CLI flags in verb mode — §5.11). Every action call is wrapped in `Timeout.timeout(2)`; exceptions and timeouts surface as `usage` errors that abort the refresh.
 
-**Built-in fetchers.** `json`, `csv`, `markdown-links`, `ical-events`, `rss` are always available. They expect raw bytes in `config["bytes"]` and produce structured frontmatter/body. Built-ins do not perform I/O themselves — the caller (or an outer fetcher) is responsible for supplying bytes.
+**Built-in actions.** `json`, `csv`, `markdown-links`, `ical-events`, `rss` are always available. They expect raw bytes in `config["bytes"]` and produce structured frontmatter/body. Built-ins do not perform I/O themselves — the caller (or an outer action) is responsible for supplying bytes.
 
 **Refresh paths.** Two are supported:
 
-1. **In-process** — `textus refresh KEY --as=script` resolves the entry's `source.fetcher`, invokes it with `(config:, store:)`, and writes the result under role `script`.
+1. **In-process** — `textus refresh KEY --as=script` resolves the entry's `source.action`, invokes it with `(config:, store:, args: {})`, and writes the result under role `script`.
 2. **External runner** — a cron job or agent harness reads `textus list --zone=intake --stale --format=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=script --stdin`.
 
-Both paths share the same role gate, audit-log entry, and `:refresh` event (§5.10). User-supplied fetchers live in `.textus/extensions/*.rb` and auto-load at `Store#initialize` (§5.11).
+Both paths share the same role gate, audit-log entry, and `:refresh` event (§5.10). User-supplied actions live in `.textus/extensions/*.rb` and auto-load at `Store#initialize` (§5.11).
 
 ### 5.5 Pending / accept workflow
 
@@ -419,29 +419,39 @@ Textus does NOT invoke these — they surface only through `textus extensions li
 
 **Removed.** The v1.1 `on_stale` event is removed in 0.2. Staleness is a poll, surfaced by `textus stale`. The `on_`-prefix convention from v1.1 is gone; events are bare symbols.
 
-### 5.11 Extension surface (v1.2)
+### 5.11 Extension surface (v1.3)
 
-Three DSL verbs cover all user-supplied code:
+Four DSL verbs cover all user-supplied code:
 
 ```
-Textus.fetcher(:name)       do |config:, store:|   ... end   # returns {frontmatter:, body:} | {content:} | {body:}
-Textus.reducer(:name)       do |rows:, config:|    ... end   # returns rows
-Textus.hook(:event, :name)  do |**kwargs|          ... end   # side effects; return ignored
+Textus.action(:name)         do |config:, store:, args:|  ... end   # intake mode: returns content; verb mode: writes via store.put
+Textus.reducer(:name)        do |rows:, config:|          ... end   # returns rows
+Textus.hook(:event, :name)   do |**kwargs|                ... end   # side effects; return ignored
+Textus.doctor_check(:name)   do |store:|                  ... end   # returns array of issue hashes
 ```
 
 Files in `.textus/extensions/*.rb` are loaded at `Store#initialize`, in lexical order, with the registry installed as the current registry for that store. Registries are per-Store: two Store instances in the same process do not share state.
 
-Failure modes:
+**Action invocation modes.**
 
-| Surface  | Timeout    | Exception                                   | Bad return |
-|----------|------------|---------------------------------------------|------------|
-| fetcher  | aborts op  | aborts op (wrapped as `UsageError`)         | aborts op  |
-| reducer  | aborts op  | aborts op                                   | aborts op  |
-| hook     | logged     | logged (audit `event_error` row)            | n/a        |
+| Mode    | Invoked by                | `config:`              | `store:`               | `args:`              | Return                                  |
+|---------|---------------------------|------------------------|------------------------|----------------------|------------------------------------------|
+| intake  | `textus refresh KEY`      | manifest `source.config` | writable view (role from `--as`) | `{}`                | required; normalized into entry write    |
+| verb    | `textus action NAME ...`  | `{}`                   | writable view (role from `--as`) | parsed CLI kv hash   | ignored                                  |
+| put-fetch | `textus put K --action=N --stdin` | `{ "bytes" => stdin }` | read-only view         | `{}`                 | required; merged into the put payload    |
 
-Fetchers and reducers are pure transforms; return values flow into the store. Hooks are side effects; return values are discarded.
+**Failure modes:**
 
-The `store:` argument is always a `Textus::StoreView` — a read-only proxy exposing `get`, `list`, `where`, `schema_envelope`, `deps`, `rdeps`, `published`, `stale`, `validate_all`. Write attempts raise `Textus::UsageError`.
+| Surface         | Timeout    | Exception                                   | Bad return |
+|-----------------|------------|---------------------------------------------|------------|
+| action          | aborts op  | aborts op (wrapped as `UsageError`)         | aborts op  |
+| reducer         | aborts op  | aborts op                                   | aborts op  |
+| hook            | logged     | logged (audit `event_error` row)            | n/a        |
+| doctor_check    | reported as `doctor_check.timeout` issue | reported as `doctor_check.failed` issue | reported as `doctor_check.bad_return` |
+
+Actions and reducers are pure transforms in modes where their return matters; their return values flow into the store. Hooks and doctor_checks shape side outputs (event chain, doctor report) — only doctor_check return values are merged.
+
+The `store:` argument is always a `Textus::StoreView`. In intake and verb modes it is writable and bound to the calling role; in put-fetch mode and inside doctor_checks it is read-only. Write attempts on a read-only view raise `Textus::UsageError`.
 
 ### 5.12 Storage formats (v1.2)
 
@@ -585,7 +595,7 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 | `deps K` / `rdeps K` | read | any |
 | `published` | read | any |
 | `validate-all` | read | any |
-| `put K --stdin --as=R [--fetcher=NAME]` | write | per zone |
+| `put K --stdin --as=R [--action=NAME]` | write | per zone |
 | `delete K --if-etag=E --as=R` | write | per zone |
 | `refresh K --as=script` | write | per zone (typically `script`) |
 | `build [--prefix=K] [--dry-run]` | write | `build` (default) |
@@ -595,7 +605,7 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 | `migrate-keys [--dry-run\|--write]` | write (with `--write`) | `human` |
 | `mv OLD NEW [--as=R] [--dry-run]` | write | per zone (same-zone only) |
 | `uid K` | read | any |
-| `extensions list [--kind=fetcher\|reducer\|hook]` | read | any |
+| `extensions list [--kind=action\|reducer\|hook]` | read | any |
 | `doctor [--format=json]` | read | any |
 | `intro [--format=json]` | read | any |
 

data/lib/textus/{builtin_fetchers.rb → builtin_actions.rb}

@@ -4,31 +4,35 @@ require "yaml"
 require "rexml/document"
 
 module Textus
-  module BuiltinFetchers
+  module BuiltinActions
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def self.register_all
-      Textus.fetcher(:json) do |config:, store:|
+      Textus.action(:json) do |config:, store:, args:|
         _ = store
+        _ = args
         data = JSON.parse(config["bytes"].to_s)
         { frontmatter: {}, body: YAML.dump(data) }
       end
 
-      Textus.fetcher(:csv) do |config:, store:|
+      Textus.action(:csv) do |config:, store:, args:|
         _ = store
+        _ = args
         rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
         { frontmatter: {}, body: YAML.dump(rows) }
       end
 
-      Textus.fetcher(:"markdown-links") do |config:, store:|
+      Textus.action(:"markdown-links") do |config:, store:, args:|
         _ = store
+        _ = args
         links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
           { "text" => text, "href" => href }
         end
         { frontmatter: {}, body: YAML.dump(links) }
       end
 
-      Textus.fetcher(:"ical-events") do |config:, store:|
+      Textus.action(:"ical-events") do |config:, store:, args:|
         _ = store
+        _ = args
         events = []
         current = nil
         config["bytes"].to_s.each_line do |line|
@@ -45,8 +49,9 @@ module Textus
         { frontmatter: {}, body: YAML.dump(events) }
       end
 
-      Textus.fetcher(:rss) do |config:, store:|
+      Textus.action(:rss) do |config:, store:, args:|
         _ = store
+        _ = args
         doc = REXML::Document.new(config["bytes"].to_s)
         items = doc.elements.to_a("//item").map do |item|
           {

data/lib/textus/cli.rb

@@ -44,6 +44,7 @@ module Textus
       when "schema-init"    then verb_schema_init(argv)
       when "schema-diff"    then verb_schema_diff(argv)
       when "schema-migrate" then verb_schema_migrate(argv)
+      when "action"         then verb_action(argv)
       when "refresh"        then verb_refresh(argv)
       when "extensions"     then verb_extensions(argv)
       when "migrate-keys"   then verb_migrate_keys(argv)
@@ -133,11 +134,11 @@ module Textus
       key = argv.shift or raise UsageError.new("put requires a key")
       as_flag = nil
       use_stdin = false
-      fetcher_name = nil
+      action_name = nil
       OptionParser.new do |o|
         o.on("--stdin") { use_stdin = true }
         o.on("--as=ROLE") { |v| as_flag = v }
-        o.on("--fetcher=NAME") { |v| fetcher_name = v }
+        o.on("--action=NAME") { |v| action_name = v }
         o.on("--format=FMT") {}
       end.permute!(argv)
       raise UsageError.new("put requires --stdin in v1") unless use_stdin
@@ -146,16 +147,16 @@ module Textus
 
       raw = @stdin.read
       payload =
-        if fetcher_name
-          callable = store.registry.fetcher(fetcher_name)
+        if action_name
+          callable = store.registry.action(action_name)
           result =
             begin
-              Timeout.timeout(Textus::Refresh::FETCHER_TIMEOUT_SECONDS) do
-                callable.call(config: { "bytes" => raw }, store: Textus::StoreView.new(store))
+              Timeout.timeout(Textus::Refresh::ACTION_TIMEOUT_SECONDS) do
+                callable.call(config: { "bytes" => raw }, store: Textus::StoreView.new(store), args: {})
               end
             rescue Timeout::Error
               raise UsageError.new(
-                "fetcher '#{fetcher_name}' exceeded #{Textus::Refresh::FETCHER_TIMEOUT_SECONDS}s timeout",
+                "action '#{action_name}' exceeded #{Textus::Refresh::ACTION_TIMEOUT_SECONDS}s timeout",
               )
             end
           basename = key.split(".").last
@@ -163,7 +164,7 @@ module Textus
             "frontmatter" => {
               "name" => basename,
               "last_refreshed_at" => Time.now.utc.iso8601,
-              "fetched_with" => fetcher_name,
+              "actioned_with" => action_name,
             }.merge(result[:frontmatter] || result["frontmatter"] || {}),
             "body" => result[:body] || result["body"] || "",
           }
@@ -271,6 +272,43 @@ module Textus
       emit(store.accept(key, as: role))
     end
 
+    def verb_action(argv)
+      name = argv.shift
+      raise UsageError.new("action requires a name") if name.nil?
+
+      as_flag = nil
+      args = {}
+      argv.each do |tok|
+        case tok
+        when /\A--as=(.+)\z/         then as_flag = ::Regexp.last_match(1)
+        when /\A--format=/           then next
+        when /\A--([\w-]+)=(.*)\z/   then args[::Regexp.last_match(1)] = ::Regexp.last_match(2)
+        else
+          raise UsageError.new("unknown arg to 'action #{name}': #{tok}")
+        end
+      end
+
+      role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+      callable = store.registry.action(name)
+      view = StoreView.new(store, writable: true, as: role)
+
+      begin
+        Timeout.timeout(Textus::Refresh::ACTION_TIMEOUT_SECONDS) do
+          callable.call(config: {}, store: view, args: args)
+        end
+      rescue Timeout::Error
+        raise UsageError.new(
+          "action '#{name}' exceeded #{Textus::Refresh::ACTION_TIMEOUT_SECONDS}s timeout",
+        )
+      rescue Textus::Error
+        raise
+      rescue StandardError => e
+        raise UsageError.new("action '#{name}' raised: #{e.class}: #{e.message}")
+      end
+
+      emit({ "protocol" => Textus::PROTOCOL, "action" => name, "ok" => true })
+    end
+
     def verb_refresh(argv)
       key = argv.shift or raise UsageError.new("refresh requires a key")
       as_flag = nil
@@ -293,7 +331,8 @@ module Textus
       end.permute!(argv)
 
       rows = []
-      rows += store.registry.fetcher_names.map { |n| { "kind" => "fetcher", "name" => n.to_s } }
+      rows += store.registry.action_names.map { |n| { "kind" => "action", "name" => n.to_s } }
+      rows += store.registry.doctor_check_names.map { |n| { "kind" => "doctor_check", "name" => n.to_s } }
       rows += store.registry.reducer_names.map { |n| { "kind" => "reducer", "name" => n.to_s } }
       store.registry.hook_events.each do |evt|
         store.registry.hooks(evt).each do |h|
@@ -388,9 +427,10 @@ module Textus
           textus list [--prefix=KEY] --format=json
           textus where KEY --format=json
           textus get KEY --format=json
-          textus put KEY --stdin --format=json
+          textus put KEY --stdin [--action=NAME] --format=json
           textus schema KEY --format=json
           textus stale [--prefix=KEY] --format=json
+          textus action NAME [--key=val ...] [--as=ROLE] --format=json
       HELP
     end
   end

data/lib/textus/doctor.rb

@@ -1,12 +1,14 @@
 require "digest"
 require "json"
+require "timeout"
 
 module Textus
   # Health check for a Textus store. Returns a JSON-friendly Hash envelope
   # with an `issues` array and a summary. Each issue is a Hash with
   # `code`, `level`, `subject`, `message`, and optionally `fix`.
-  module Doctor
+  module Doctor # rubocop:disable Metrics/ModuleLength -- 8 built-in checks + extension dispatch
     LEVELS = %w[error warning info].freeze
+    DOCTOR_CHECK_TIMEOUT_SECONDS = 2
 
     module_function
 
@@ -20,6 +22,7 @@ module Textus
       issues.concat(check_sentinels(store))
       issues.concat(check_audit_log(store))
       issues.concat(check_unowned_schema_fields(store))
+      issues.concat(run_registered_checks(store))
 
       summary = LEVELS.to_h { |l| [l, issues.count { |i| i["level"] == l }] }
       {
@@ -255,6 +258,43 @@ module Textus
       out
     end
 
+    def run_registered_checks(store)
+      out = []
+      view = StoreView.new(store)
+      store.registry.doctor_check_names.each do |name|
+        callable = store.registry.doctor_check(name)
+        begin
+          result = Timeout.timeout(DOCTOR_CHECK_TIMEOUT_SECONDS) { callable.call(store: view) }
+          if result.is_a?(Array)
+            out.concat(result.map { |h| h.transform_keys(&:to_s) })
+          else
+            out << fail_issue(name, code: "doctor_check.bad_return",
+                                    message: "doctor_check '#{name}' returned #{result.class} (expected Array)",
+                                    fix: "return an array of issue hashes from the doctor_check block")
+          end
+        rescue Timeout::Error
+          out << fail_issue(name, code: "doctor_check.timeout",
+                                  message: "doctor_check '#{name}' exceeded #{DOCTOR_CHECK_TIMEOUT_SECONDS}s",
+                                  fix: "shorten the check or split it into smaller checks")
+        rescue StandardError => e
+          out << fail_issue(name, code: "doctor_check.failed",
+                                  message: "#{e.class}: #{e.message}",
+                                  fix: "fix the doctor_check block in .textus/extensions/")
+        end
+      end
+      out
+    end
+
+    def fail_issue(name, code:, message:, fix:)
+      {
+        "code" => code,
+        "level" => "error",
+        "subject" => name.to_s,
+        "message" => message,
+        "fix" => fix,
+      }
+    end
+
     # --- Helpers ----------------------------------------------------------
 
     def leaf_path_for(store, entry)

data/lib/textus/extension_registry.rb

@@ -3,16 +3,17 @@ module Textus
     EVENTS = %i[put delete refresh build accept].freeze
 
     def initialize
-      @fetchers = {}
+      @actions = {}
       @reducers = {}
       @hooks = {}
+      @doctor_checks = {}
     end
 
-    def register_fetcher(name, &blk)
+    def register_action(name, &blk)
       name = name.to_sym
-      raise UsageError.new("fetcher '#{name}' already registered") if @fetchers.key?(name)
+      raise UsageError.new("action '#{name}' already registered") if @actions.key?(name)
 
-      @fetchers[name] = blk
+      @actions[name] = blk
     end
 
     def register_reducer(name, &blk)
@@ -29,8 +30,15 @@ module Textus
       (@hooks[event] ||= []) << { name: name.to_sym, callable: blk }
     end
 
-    def fetcher(name)
-      @fetchers[name.to_sym] or raise UsageError.new("unknown fetcher: #{name}")
+    def register_doctor_check(name, &blk)
+      name = name.to_sym
+      raise UsageError.new("doctor_check '#{name}' already registered") if @doctor_checks.key?(name)
+
+      @doctor_checks[name] = blk
+    end
+
+    def action(name)
+      @actions[name.to_sym] or raise UsageError.new("unknown action: #{name}")
     end
 
     def reducer(name)
@@ -41,8 +49,13 @@ module Textus
       @hooks[event.to_sym] || []
     end
 
-    def fetcher_names = @fetchers.keys
-    def reducer_names = @reducers.keys
-    def hook_events   = @hooks.keys
+    def doctor_check(name)
+      @doctor_checks[name.to_sym] or raise UsageError.new("unknown doctor_check: #{name}")
+    end
+
+    def action_names        = @actions.keys
+    def reducer_names       = @reducers.keys
+    def hook_events         = @hooks.keys
+    def doctor_check_names  = @doctor_checks.keys
   end
 end

data/lib/textus/extensions.rb

@@ -15,8 +15,8 @@ module Textus
       raise UsageError.new("no active registry; extension code must be loaded by a Store")
   end
 
-  def self.fetcher(name, &)
-    current_registry.register_fetcher(name, &)
+  def self.action(name, &)
+    current_registry.register_action(name, &)
   end
 
   def self.reducer(name, &)
@@ -26,4 +26,8 @@ module Textus
   def self.hook(event, name, &)
     current_registry.register_hook(event, name, &)
   end
+
+  def self.doctor_check(name, &)
+    current_registry.register_doctor_check(name, &)
+  end
 end

data/lib/textus/init.rb

@@ -31,12 +31,13 @@ module Textus
       File.write(File.join(target_root, "extensions", "README.md"), <<~MD)
         # Extensions
 
-        Drop one Ruby file per extension. Three verbs are available:
+        Drop one Ruby file per extension. Four verbs are available:
 
         ```ruby
-        Textus.fetcher(:name)        { |config:, store:| ... }
-        Textus.reducer(:name)        { |rows:, config:| ... }
-        Textus.hook(:event, :name)   { |key:, envelope:, store:, **kw| ... }
+        Textus.action(:name)         { |config:, store:, args:| ... }
+        Textus.reducer(:name)        { |rows:, config:|         ... }
+        Textus.hook(:event, :name)   { |key:, envelope:, **kw|  ... }
+        Textus.doctor_check(:name)   { |store:|                 ... }
         ```
 
         Events: :put, :delete, :refresh, :build, :accept.

data/lib/textus/intro.rb

@@ -13,7 +13,7 @@ module Textus
     ZONE_PURPOSES = {
       "canon" => "slow-changing identity; human-only writes",
       "working" => "active project state; humans, AI, and scripts share this surface",
-      "intake" => "declared external inputs; script-refreshed via fetchers",
+      "intake" => "declared external inputs; script-refreshed via actions",
       "pending" => "AI proposals awaiting human accept",
       "derived" => "build-computed outputs; never hand-edited",
     }.freeze
@@ -22,7 +22,7 @@ module Textus
       "human" => "edit files in canon/working zones, then 'textus put KEY --as=human'",
       "ai" => "propose changes by writing 'pending.*' entries with --as=ai and a 'proposal:' frontmatter block; " \
               "a human runs 'textus accept' to apply",
-      "script" => "refresh intake entries with 'textus refresh KEY --as=script' (uses the entry's declared fetcher)",
+      "script" => "refresh intake entries with 'textus refresh KEY --as=script' (uses the entry's declared action)",
       "build" => "'textus build' computes derived entries from projections; derived files are never hand-edited",
     }.freeze
 
@@ -40,11 +40,11 @@ module Textus
       { "name" => "mv",       "summary" => "rename a key in place; uid preserved, audit row written" },
       { "name" => "delete",   "summary" => "delete an entry; --as=<role>" },
       { "name" => "build",    "summary" => "materialize derived entries; publish_to and publish_each fan out copies" },
-      { "name" => "refresh",  "summary" => "run a fetcher for an intake entry" },
+      { "name" => "refresh",  "summary" => "run an action for an intake entry" },
       { "name" => "stale",    "summary" => "list derived/intake entries past their freshness check" },
       { "name" => "doctor",   "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
       { "name" => "migrate-keys", "summary" => "rename files whose basenames violate the strict key grammar" },
-      { "name" => "extensions", "summary" => "list registered reducers/fetchers/hooks" },
+      { "name" => "extensions", "summary" => "list registered actions, reducers, doctor_checks, declared hooks" },
     ].freeze
 
     def self.run(store)
@@ -80,7 +80,7 @@ module Textus
           "owner" => e.owner,
           "format" => e.format,
           "derived" => derived,
-          "intake" => !e.fetcher.nil?,
+          "intake" => !e.action.nil?,
           "publish_to" => Array(e.publish_to),
           "publish_each" => e.publish_each,
         }
@@ -90,13 +90,15 @@ module Textus
     def self.extensions_for(store)
       reg = store.registry
       reducers = reg.reducer_names.map(&:to_s).sort
-      fetchers = reg.fetcher_names.map(&:to_s).sort
+      actions = reg.action_names.map(&:to_s).sort
+      doctor_checks = reg.doctor_check_names.map(&:to_s).sort
       hooks = reg.hook_events.flat_map do |evt|
         reg.hooks(evt).map { |h| { "event" => evt.to_s, "name" => h[:name].to_s } }
       end.sort_by { |h| [h["event"], h["name"]] }
       {
         "reducers" => reducers,
-        "fetchers" => fetchers,
+        "actions" => actions,
+        "doctor_checks" => doctor_checks,
         "hooks" => hooks,
       }
     end

data/lib/textus/manifest.rb

@@ -199,7 +199,7 @@ module Textus
     PUBLISH_EACH_VAR_RE = /\{([a-z]+)\}/
 
     attr_reader :key, :path, :zone, :schema, :owner, :nested, :generator, :raw, :format,
-                :projection, :template, :publish_to, :publish_each, :fetcher, :fetcher_config, :ttl, :events,
+                :projection, :template, :publish_to, :publish_each, :action, :action_config, :ttl, :events,
                 :inject_intro
 
     def initialize(manifest, raw)
@@ -361,8 +361,8 @@ module Textus
 
     def parse_source!(src)
       src ||= {}
-      @fetcher = src["fetcher"]
-      @fetcher_config = src["config"] || {}
+      @action = src["action"]
+      @action_config = src["config"] || {}
       @ttl = src["ttl"]
     end
 
@@ -371,7 +371,13 @@ module Textus
       if src.key?("parse") || src.key?("from")
         raise UsageError.new(
           "entry '#{@key}': source.parse/source.from removed in 0.2; " \
-          "use source.fetcher (+ source.config). See SPEC §5.4.",
+          "use source.action (+ source.config). See SPEC §5.4.",
+        )
+      end
+      if src.key?("fetcher")
+        raise UsageError.new(
+          "entry '#{@key}': source.fetcher renamed to source.action in 0.4; " \
+          "rename the key. See SPEC §5.4.",
         )
       end
       if raw.key?("hooks")

data/lib/textus/refresh.rb

@@ -2,27 +2,29 @@ require "timeout"
 
 module Textus
   module Refresh
-    FETCHER_TIMEOUT_SECONDS = 2
+    ACTION_TIMEOUT_SECONDS = 2
 
     def self.call(store, key, as:)
       mentry, path, = store.manifest.resolve(key)
-      raise UsageError.new("no fetcher declared for '#{key}'") unless mentry.fetcher
+      raise UsageError.new("no action declared for '#{key}'") unless mentry.action
 
       before_etag = File.exist?(path) ? Etag.for_file(path) : nil
-      callable = store.registry.fetcher(mentry.fetcher)
-      view = StoreView.new(store)
+      callable = store.registry.action(mentry.action)
+      view = StoreView.new(store, writable: true, as: as)
       result =
         begin
-          Timeout.timeout(FETCHER_TIMEOUT_SECONDS) { callable.call(config: mentry.fetcher_config, store: view) }
+          Timeout.timeout(ACTION_TIMEOUT_SECONDS) do
+            callable.call(config: mentry.action_config, store: view, args: {})
+          end
         rescue Timeout::Error
-          raise UsageError.new("fetcher '#{mentry.fetcher}' exceeded #{FETCHER_TIMEOUT_SECONDS}s timeout")
+          raise UsageError.new("action '#{mentry.action}' exceeded #{ACTION_TIMEOUT_SECONDS}s timeout")
         rescue Textus::Error
           raise
         rescue StandardError => e
-          raise UsageError.new("fetcher '#{mentry.fetcher}' raised: #{e.class}: #{e.message}")
+          raise UsageError.new("action '#{mentry.action}' raised: #{e.class}: #{e.message}")
         end
 
-      normalized = normalize_fetcher_result(result, format: mentry.format)
+      normalized = normalize_action_result(result, format: mentry.format)
       envelope = store.put(
         key,
         frontmatter: normalized[:frontmatter],
@@ -43,9 +45,9 @@ module Textus
       envelope
     end
 
-    # Normalize the three accepted fetcher return shapes into the store's
-    # internal {frontmatter, body, content} representation. See plan-1.2 §7.
-    def self.normalize_fetcher_result(res, format:)
+    # Normalize the three accepted action return shapes into the store's
+    # internal {frontmatter, body, content} representation.
+    def self.normalize_action_result(res, format:)
       res = res.transform_keys(&:to_s) if res.is_a?(Hash)
       res ||= {}
       fm      = res["frontmatter"]
@@ -62,10 +64,9 @@ module Textus
           meta = content.is_a?(Hash) && content["_meta"].is_a?(Hash) ? content["_meta"] : {}
           { frontmatter: meta, body: nil, content: content }
         elsif !body.nil?
-          # Store#put will re-parse and validate the bytes.
           { frontmatter: {}, body: body.to_s, content: nil }
         else
-          raise UsageError.new("fetcher for #{format} returned neither content nor body")
+          raise UsageError.new("action for #{format} returned neither content nor body")
         end
       else
         raise UsageError.new("unknown format #{format.inspect}")

data/lib/textus/store.rb

@@ -51,7 +51,7 @@ module Textus
 
     def load_extensions
       Textus.with_registry(@registry) do
-        BuiltinFetchers.register_all
+        BuiltinActions.register_all
         dir = File.join(@root, "extensions")
         return unless File.directory?(dir)
 
@@ -296,7 +296,7 @@ module Textus
       end
 
       @manifest.entries.each do |mentry|
-        next unless mentry.fetcher
+        next unless mentry.action
         next if zone && mentry.zone != zone
         next if prefix && !(mentry.key == prefix || mentry.key.start_with?("#{prefix}."))
 
@@ -529,7 +529,7 @@ module Textus
     end
 
     def intake_stale_row(mentry, path, reason)
-      { "key" => mentry.key, "path" => path, "fetcher" => mentry.fetcher, "reason" => reason }
+      { "key" => mentry.key, "path" => path, "action" => mentry.action, "reason" => reason }
     end
 
     def stale_row(mentry, path, reason)

data/lib/textus/store_view.rb

@@ -3,8 +3,12 @@ module Textus
     READ_METHODS  = %i[get list where schema_envelope deps rdeps published stale validate_all].freeze
     WRITE_METHODS = %i[put delete accept].freeze
 
-    def initialize(store)
+    def initialize(store, writable: false, as: nil)
+      raise UsageError.new("writable StoreView requires an as: role") if writable && (as.nil? || as.to_s.empty?)
+
       @store = store
+      @writable = writable
+      @as = as
     end
 
     READ_METHODS.each do |m|
@@ -12,7 +16,12 @@ module Textus
     end
 
     WRITE_METHODS.each do |m|
-      define_method(m) { |*_args, **_kw| raise UsageError.new("StoreView is read-only") }
+      define_method(m) do |*args, **kw|
+        raise UsageError.new("StoreView is read-only") unless @writable
+
+        kw[:as] = @as unless kw.key?(:as)
+        @store.public_send(m, *args, **kw)
+      end
     end
   end
 end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
   PROTOCOL = "textus/1"
 end

data/lib/textus.rb

@@ -19,7 +19,7 @@ require_relative "textus/store_view"
 require_relative "textus/refresh"
 require_relative "textus/mustache"
 require_relative "textus/projection"
-require_relative "textus/builtin_fetchers"
+require_relative "textus/builtin_actions"
 require_relative "textus/publisher"
 require_relative "textus/builder"
 require_relative "textus/proposal"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Patrick
@@ -97,7 +97,7 @@ files:
 - lib/textus.rb
 - lib/textus/audit_log.rb
 - lib/textus/builder.rb
-- lib/textus/builtin_fetchers.rb
+- lib/textus/builtin_actions.rb
 - lib/textus/cli.rb
 - lib/textus/dependencies.rb
 - lib/textus/doctor.rb