textus 0.10.4 → 0.10.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efe7d1a6ddffa757d720b66fbd52c0685691e4b2b6beaa042552b7f154878f21
-  data.tar.gz: f8eb5a0656c343d4b6990710aa39ecf80d1a19908f4b9d9be365ab19bf443deb
+  metadata.gz: 79987029ce43500b025495ef26cefc285f7a748cdcd43388aff2fefafdf4c0ca
+  data.tar.gz: 44a9d40720a84e4e942a1c4fde9e0ed9e7773126f443b247f6d8cb27d630c204
 SHA512:
-  metadata.gz: ac44def8227532f58b69da7c0d6f1783299a174f1ac4e278074aba52a20de3da6bc14fd0df10db824dce8991a6bd65ba970994d703702586dce0ae91f66a89fa
-  data.tar.gz: 6a3e41cc32743bb1a7ff8cb23a16d8a775bfa1ec0758fb69398047ec8517a8d47579e9c2ab6e78159a064b8f7624591aa34f3667151324c72bd5f8c6050e4be4
+  metadata.gz: a539030b1d406226bbe3d3fad03b3daee59094d3d8db351d97c9c5adc445ca8c188a7d13a16cdfaaae0c933091e6a8858c14a91362f461f25a1dce52aa04a60f
+  data.tar.gz: 83667dab7c91d4c2e9def3c2a2d605cf45d84f3fdf89bf0e6d8d25ff2b8fe668d6b71ceae0488e7ffe24970bf80e0f5eeeb13c308b2d16c9d11fc41633160dd6

data/CHANGELOG.md

@@ -8,6 +8,30 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 (currently `textus/2`, embedded in every envelope as `protocol`). The protocol
 is additive within a major; a new major would change the wire string.
 
+## [Unreleased]
+
+## 0.10.5 — tech-debt cleanup + `index_filename:` + docs polish (2026-05-25)
+
+Patch release. One user-facing feature (`index_filename:` on nested manifest entries) plus internal refactors that remove 7 of 19 `rubocop:disable` suppressions. No protocol bump; existing manifests parse unchanged.
+
+### Added
+
+- **Per-entry `index_filename:` on nested manifest entries.** A nested entry MAY declare `index_filename: SKILL.md` (or any other bare basename) to surface that single file per directory as the row; the row's key segments come from the directory path, and siblings are not enumerated. Lets entries project spec-mandated filenames (e.g. agentskills.io's `SKILL.md`) whose uppercase casing would otherwise be rejected by the `[a-z0-9][a-z0-9-]*` key-segment grammar. `resolve(key)` returns the index-filename path for sub-directories. Validation: requires `nested: true`, basename only (no slashes), extension must match the entry's `format:`. New spec `spec/manifest_index_filename_spec.rb`. Documented in SPEC §4.
+
+### Internal
+
+- **`Store::Mover#call` refactor.** Replaces an 81-line method (suppressed `Metrics/AbcSize, Metrics/MethodLength`) with an 8-line orchestrator sequenced over four named private phases — `prepare_plan`, `ensure_uid!`, `perform_move`, `record_move` — coordinated through a `MovePlan` value object. The pre-read envelope is threaded separately so `MovePlan` describes only the planned operation.
+- **`Store::Staleness#call` split.** Replaces a 70-line dual-loop method (the most aggressive suppression in the gem — `AbcSize, CyclomaticComplexity, MethodLength, PerceivedComplexity, BlockLength`) with a composer + two single-purpose checks (`GeneratorCheck`, `IntakeCheck`) and a private filter method on the composer. Each new unit fits default rubocop thresholds.
+- **`Store::Writer` payload + ctx grouping.** Collapses `write_envelope_to_disk`'s 8 keyword args to 5 by introducing `Store::Writer::Payload = Data.define(:meta, :body, :content)` and reusing `Application::Context` for `role` + `correlation_id`. Applies the same `ctx:` pattern to the sibling `delete_envelope_from_disk`. The class-wide `Metrics/ParameterLists` disable is narrowed to a method-level disable on the `put` back-compat shim (which mirrors the user-facing `Store#put` 7-kwarg signature and cannot be changed).
+- **Net suppression change:** 19 `rubocop:disable` lines → 17; 7 metric-cop suppressions removed; one `ParameterLists` disable narrowed in scope. Full suite unchanged.
+
+### Documentation
+
+- **SPEC.md §5.2.1 added.** Documents the `generator:` field — the externally-generated-derived-entry shape (build runner produces the file; textus tracks `sources:` for staleness via `_meta.generated.at`). The field was always parsed and tested but had no spec coverage. Clarifies that textus never executes `command:` — consistent with §2 "Not an executor."
+- **README.md trimmed.** Removed the duplicated "CLI verbs" and "Zones and roles" tables; readers are pointed at SPEC §5 / §9 and `docs/zones.md` for the canonical surfaces. README narrative kept.
+- **docs/conventions.md** now covers both derived-entry shapes (`projection:` for declarative compute inside textus; `generator:` for external build tools) and the current intake / freshness model (top-level `policies:` + `textus refresh-stale`). Replaces a stale section that described a pre-0.4 build-runner pattern.
+- **CONTRIBUTING.md** sources-of-truth pointer updated. Per-release implementation plans are kept locally by maintainers and no longer signposted in public docs.
+
 ## 0.10.4 — GitHub folder intake recipe + skill-bundle deferral ADR (2026-05-24)
 
 Patch release. Ships a working "pull a GitHub folder as a skill bundle, fan it out to derived entries" pattern as opt-in example hooks under `examples/claude-plugin/recipes/`, with hermetic specs and user-facing docs. Captures the design decision to defer first-class skill-bundle support to a future release. No `lib/` changes; CLI, wire protocol, event surface, manifest schema, and doctor checks are all unchanged.
@@ -42,7 +66,7 @@ Patch release. Two pieces of work: (1) docs describe current state only — ever
 
 ### Documentation
 
-- **`docs/plans/`** is now signposted in `CONTRIBUTING.md` as design history, not current documentation.
+- **`CONTRIBUTING.md`** now points readers at SPEC / ARCHITECTURE / `docs/` / CHANGELOG as the sources of truth. Per-release implementation plans are kept locally by maintainers and are no longer signposted in public docs.
 - **README, SPEC, ARCHITECTURE, docs/zones, docs/events, docs/conventions, examples/claude-plugin/README** — stripped `(0.8.2+)`, `(0.9.0+)`, `(0.9.2)`, `(v1.0)`, `(v1.1)`, `(v1.2)`, `(v0.3)` annotations from headings, parentheticals, and inline notes. Removed "Renamed in 0.9.2" / "Pre-0.9.2 stores" / "New in 0.9.0" / "Backward compatibility (v0.5)" callouts. Example code that used pre-0.9.2 zone names (`canon`, `intake`, `pending`, `derived`) now uses current names (`identity`, `inbox`, `review`, `output`).
 - **`docs/events.md`** — header count corrected to "15 events: 3 RPC and 12 pub-sub" (previously read "12 events", with refresh\_\* mentioned in subtext); stale Linear manifest example updated to use top-level `policies:` block.
 - **SPEC.md §10.2** — removed `legacy_intake_fields` from the builtin doctor-check list.

data/README.md

@@ -85,68 +85,14 @@ For the full shape — Claude plugin with agents, skills, commands, pending walk
 
 Symlink-mode publish was removed; publish is `FileUtils.cp` + sentinel. Sentinels for published files live under `.textus/sentinels/<target_rel>.textus-managed.json` so consumer directories stay clean. Legacy sibling sentinels auto-migrate on next publish.
 
-## CLI verbs
-
-All verbs accept `--format=json` and return the envelope defined in SPEC §8. Write verbs require `--as=<role>` (role resolution: `--as` → `TEXTUS_ROLE` env → `.textus/role` file → default `human`).
-
-**Read:**
-
-| Verb | Purpose |
-|---|---|
-| `intro` | Store orientation: zones, entries, hooks, write flows, CLI map |
-| `list [--prefix=K] [--zone=Z]` | Enumerate keys |
-| `where K` | Resolve a key to its filesystem path |
-| `get K` | Full envelope (frontmatter, body, uid, etag, format) |
-| `schema show K` | Schema bound to an entry |
-| `freshness [--prefix=K] [--zone=Z]` | Per-entry status (fresh / stale / never_refreshed / no_policy) against `policies:` |
-| `audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]` | Query `.textus/audit.log` |
-| `blame KEY` | Audit rows joined with git commit metadata |
-| `policy list` / `policy explain KEY` | Dump effective policies / per-slot winners for one key |
-| `deps K` / `rdeps K` | Forward / reverse projection dependencies |
-| `published` | List `publish_to:` targets and their backing keys |
-| `doctor --check=schema_violations` | Validate every entry against its schema |
-| `hook list [--event=E]` | Registered hooks grouped by event (intake, reduce, check, put, deleted, refreshed, built, accepted, published, mv, reject, loaded, refresh_began, refresh_failed, refresh_detached) |
-
-**Write:**
-
-| Verb | Role |
-|---|---|
-| `put K --stdin --as=R [--action=NAME]` | per zone |
-| `hook run NAME [--key=val] [--as=R]` | per zone written (invoke a registered intake hook) |
-| `delete K --if-etag=E --as=R` | per zone |
-| `refresh K --as=script` | per zone (typically `script`) |
-| `key mv old new --as=R [--dry-run]` | per zone (same-zone moves; uid preserved) |
-| `build [--prefix=K] [--dry-run]` | `build` |
-| `accept K --as=human` | `human` only |
-| `reject K --as=human` | `human` only (discards a pending proposal; fires `:reject`) |
-
-**Health & maintenance:**
-
-| Verb | Purpose |
-|---|---|
-| `doctor` | Health checks (manifest, schemas, templates, hooks, illegal keys, sentinels, audit log, policy ambiguity, handler allowlist, legacy intake fields); `ok: true` when clean |
-| `key migrate [--dry-run]` | Rename files whose basenames violate the strict key grammar |
-
-**Scaffolding (human-only):**
-
-| Verb | Purpose |
-|---|---|
-| `init` | Scaffold a fresh `.textus/` |
-| `schema init NAME` | Stub a schema |
-| `schema diff NAME` | Compare a schema against entries that claim it |
-| `schema migrate NAME [--rename=OLD:NEW]` | Rewrite frontmatter keys across affected entries |
-
-## Zones and roles
-
-| Zone | `writable_by` | Purpose |
-|---|---|---|
-| `identity` | `[human]` | Identity, voice, decisions — slow-changing |
-| `working` | `[human, ai, script]` | Active project state |
-| `inbox` | `[script]` | Declared external inputs (actions) |
-| `review` | `[ai, human]` | AI proposals; humans run `textus accept` to apply |
-| `output` | `[build]` | Computed outputs from `textus build` |
-
-Mismatches return `write_forbidden` with a hint naming the role that *would* be allowed. Every write records the resolved role in `.textus/audit.log`.
+## CLI and zones
+
+All verbs accept `--format=json` and return the envelope defined in [SPEC §8](SPEC.md). Write verbs require `--as=<role>` (role resolution: `--as` → `TEXTUS_ROLE` env → `.textus/role` file → default `human`).
+
+- Full verb table — read, write, health, scaffolding — is in [SPEC §9](SPEC.md).
+- Zone semantics and the role/`writable_by` mapping live in [SPEC §5](SPEC.md), with a tutorial expansion in [`docs/zones.md`](docs/zones.md).
+
+`textus intro` prints the same information for the current store: zones, entry families with schemas, registered hooks, write flows, and the verb catalog. Run it inside a store and you get the live picture; reach for the SPEC when you want the contract.
 
 ## Compute and publish
 

data/SPEC.md

@@ -144,6 +144,18 @@ Zone names are conventional — the manifest is the source of truth for write pe
 
 For `nested: true`, the recursive glob matches the format's extension (markdown→`**/*.md`, json→`**/*.json`, yaml→`**/*.{yaml,yml}`, text→`**/*.txt`). All files under one nested entry share one format and one schema.
 
+**Per-entry `index_filename:`.** A nested entry MAY declare `index_filename:` to surface a single fixed basename (e.g. `SKILL.md`) per directory as the row, with the row's key segments derived from the directory path. Sibling files are not enumerated. The basename's extension MUST match the entry's `format:`. This lets entries project spec-mandated filenames whose casing would otherwise be rejected by the key-segment grammar. Example:
+
+```yaml
+- key: skills
+  path: skills
+  zone: skills
+  nested: true
+  index_filename: SKILL.md
+```
+
+A file at `.textus/zones/skills/ask/SKILL.md` enumerates as `skills.ask`; `.textus/zones/skills/ask/references/algorithm.md` is not enumerated. Resolving `skills.ask` returns the `SKILL.md` path. `index_filename:` requires `nested: true`; the value must be a bare basename (no slashes).
+
 **Per-leaf publishing (`publish_each:`).** A nested manifest entry MAY declare `publish_each:` to byte-copy every leaf to a templated repo-relative path. `publish_each:` and `publish_to:` are mutually exclusive on the same entry, and `publish_each:` requires `nested: true`. The template substitutes these variables (using `{name}` syntax):
 
 | Variable     | Value                                                                                  |
@@ -226,6 +238,44 @@ If `template` is given, it names a Mustache template under `.textus/templates/`.
 
 No partials. No lambdas. No HTML escaping (output is raw text, intended for Markdown). Template recursion depth is bounded at 8; exceeding the limit is an error.
 
+### 5.2.1 Externally-generated derived entries (`generator:`)
+
+A derived entry that is produced by a build tool *outside* textus — `rake`, `just`, a shell script, anything — declares `generator:` instead of `projection:`. textus does **not** execute the command (consistent with §2); the external runner is responsible for writing the file. textus records `sources:` so `textus freshness` can compare source mtimes against the derived file's `_meta.generated.at` and report staleness.
+
+```yaml
+- key: output.catalogs.skills
+  path: output/catalogs/skills.md
+  zone: output
+  owner: build:catalog-skills
+  generator:
+    command: "rake catalog:skills"   # informational; the runner invokes it
+    sources:                          # dotted keys OR repo-relative paths
+      - working.projects
+      - working.network
+```
+
+**`sources:`** is a list. Each element is either a dotted key prefix (matched against manifest entries) or a filesystem path (relative to the repo root, or absolute). For each key prefix, every matching entry's file mtime is checked. For each path, file or directory mtime is checked.
+
+**`command:`** is recorded in the staleness row's `generator` field but never executed. It exists so `textus freshness` output can carry a hint about how to refresh.
+
+**Freshness contract.** An entry with `generator:` is reported by `textus freshness` as `stale` when:
+- The derived file does not exist, OR
+- `_meta.generated.at` is missing or unparseable, OR
+- Any `sources:` element has been modified after `_meta.generated.at`.
+
+**Frontmatter contract.** The external runner is responsible for writing the `generated:` frontmatter block when it produces the file:
+
+```yaml
+generated:
+  by: "rake catalog:skills"
+  at: "2026-05-25T12:00:00Z"
+  from: [working.projects, working.network]
+```
+
+`generated.from` SHOULD match `generator.sources` — they're the same list, recorded twice so a diff proves what was actually consumed.
+
+`generator:` and `projection:` are alternatives — typically only one is set per entry. Templates are not required when `generator:` is declared: the runner produces the bytes directly.
+
 ### 5.3 Publish layer (`publish_to:`)
 
 A derived entry MAY declare `publish_to:` in its frontmatter, listing one or more destination paths relative to the project root:

data/docs/conventions.md

@@ -44,34 +44,66 @@ The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it
 
 Tooling around `git blame` or audit logs may filter on owner; the gem itself only echoes it back in envelopes.
 
-## Derived entries and build runners
+## Derived entries
 
-**Always** declare `generator:` on derived entries that participate in any build pipeline. Without it, `textus freshness` cannot help — the entry is just an opaque file.
+textus supports two shapes for derived entries:
+
+**`projection:`** — textus computes the entry on `textus build` from other store entries. Declarative; nothing shells out.
 
 ```yaml
-- key: output.catalogs.skills
-  path: output/catalogs/skills
+- key: output.catalogs.people
+  path: output/catalogs/people.md
   zone: output
   schema: null
+  owner: build:catalog-people
+  projection:
+    select: working.network.org   # prefix or list of prefixes
+    pluck:  [name, relationship, org]
+    sort_by: name
+  template: people.mustache       # under .textus/templates/
+  publish_to: [docs/people.md]    # optional repo-relative byte-copy targets
+```
+
+**`generator:`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `textus freshness` can compare source mtimes against the file's `_meta.generated.at`.
+
+```yaml
+- key: output.catalogs.skills
+  path: output/catalogs/skills.md
+  zone: output
   owner: build:catalog-skills
   generator:
-    command: "rake catalog:skills"
-    sources:
-      - working.projects
-      - working.network
+    command: "rake catalog:skills"   # informational; the runner invokes it
+    sources: [working.projects, working.network]
+```
+
+The build runner is responsible for writing the `generated:` frontmatter block (`by`, `at`, `from`) when it produces the file. `generated.from` SHOULD match `generator.sources` — same list, recorded twice so a diff proves what was consumed.
+
+Full contract for both shapes is in [`../SPEC.md` §5.2 and §5.2.1](../SPEC.md). Reducers (`projection.reduce:`) and per-leaf publishing (`publish_each:`) are also covered there.
+
+## Intake and freshness
+
+External inputs land via `:intake` hooks, not shell commands. Each inbox entry names a registered handler; refresh is on demand:
+
+```sh
+textus refresh inbox.notion.roadmap --as=script
+textus refresh-stale --zone=inbox --as=script   # everything past its TTL
+```
+
+Freshness budgets live in the top-level `policies:` block, matched by glob:
+
+```yaml
+policies:
+  - match: inbox.notion.**
+    refresh: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
 ```
 
-**The build runner is responsible for writing the `generated:` frontmatter block** when it regenerates. The gem will never synthesize it. A typical lefthook / rake / just integration looks like:
+A typical scheduled-refresh integration shells the `refresh-stale` sweep itself:
 
 ```sh
-textus freshness --format=json \
-  | jq -r '.rows[] | select(.status == "stale") | .key' \
-  | while read key; do
-      textus refresh "$key" --as=script
-    done
+textus refresh-stale --zone=inbox --as=script   # in cron / CI
 ```
 
-`generated.from` SHOULD match `generator.sources` from the manifest — they're the same list, recorded in two places so a diffable file proves what was actually consumed.
+See [`./zones.md` §6](zones.md) for the full intake contract and [`./events.md`](events.md) for writing custom handlers.
 
 ## Body content
 

data/lib/textus/application/writes/delete.rb

@@ -17,8 +17,7 @@ module Textus
           end
 
           @ctx.store.writer.delete_envelope_from_disk(
-            key, if_etag: if_etag, as: @ctx.role,
-                 correlation_id: @ctx.correlation_id
+            key, ctx: @ctx, if_etag: if_etag
           )
 
           unless suppress_events

data/lib/textus/application/writes/put.rb

@@ -19,12 +19,9 @@ module Textus
           envelope = @ctx.store.writer.write_envelope_to_disk(
             key,
             mentry: mentry,
-            meta: meta,
-            body: body,
-            content: content,
+            payload: Textus::Store::Writer::Payload.new(meta: meta, body: body, content: content),
+            ctx: @ctx,
             if_etag: if_etag,
-            as: @ctx.role,
-            correlation_id: @ctx.correlation_id,
           )
 
           unless suppress_events

data/lib/textus/manifest/entry.rb

@@ -7,7 +7,7 @@ module Textus
       attr_reader :key, :path, :zone, :schema, :owner, :nested, :generator, :raw, :format,
                   :projection, :template, :publish_to, :publish_each,
                   :intake_handler, :intake_config,
-                  :events, :inject_intro
+                  :events, :inject_intro, :index_filename
 
       def initialize(manifest, raw)
         @manifest = manifest
@@ -25,6 +25,7 @@ module Textus
         @publish_each = raw["publish_each"]
         @events = raw["events"] || {}
         @inject_intro = raw["inject_intro"] == true
+        @index_filename = raw["index_filename"]
         @format = resolve_format!(raw["format"])
 
         validate_events!
@@ -32,6 +33,7 @@ module Textus
         validate_format_matrix!
         validate_publish_each!
         validate_inject_intro!
+        validate_index_filename!
       end
 
       # Resolves the per-leaf target path (relative to repo root) for a full
@@ -66,6 +68,37 @@ module Textus
 
       private
 
+      # `index_filename:` makes a nested entry treat a fixed basename (e.g.
+      # `SKILL.md`) as the per-directory row. The directory path becomes the
+      # key suffix; sibling files are not enumerated. Allows projecting
+      # spec-mandated filenames that would otherwise be rejected by the
+      # lowercase-only key segment grammar.
+      def validate_index_filename!
+        return if @index_filename.nil?
+
+        raise UsageError.new("entry '#{@key}': index_filename requires nested: true") unless @nested
+        unless @index_filename.is_a?(String) && !@index_filename.empty?
+          raise UsageError.new("entry '#{@key}': index_filename must be a non-empty string")
+        end
+        if @index_filename.include?("/") || File.basename(@index_filename) != @index_filename
+          raise UsageError.new("entry '#{@key}': index_filename must be a bare basename (no slashes)")
+        end
+
+        ext = File.extname(@index_filename)
+        inferred = Manifest::EXT_TO_FORMAT[ext]
+        if inferred.nil?
+          raise UsageError.new(
+            "entry '#{@key}': index_filename #{@index_filename.inspect} has unknown extension #{ext.inspect}",
+          )
+        end
+        return if inferred == @format
+
+        raise UsageError.new(
+          "entry '#{@key}': index_filename extension #{ext.inspect} implies format #{inferred.inspect}, " \
+          "but entry format is #{@format.inspect}",
+        )
+      end
+
       def zone_writers
         @manifest.zone_writers(@zone)
       rescue UsageError => e

data/lib/textus/manifest.rb

@@ -76,8 +76,12 @@ module Textus
       else
         raise UnknownKey.new(key, suggestions: suggestions_for(key)) unless entry.nested
 
-        primary_ext = Textus::Entry.for_format(entry.format).extensions.first
-        path = File.join(@root, "zones", entry.path, *remaining) + primary_ext
+        path = if entry.index_filename
+                 File.join(@root, "zones", entry.path, *remaining, entry.index_filename)
+               else
+                 primary_ext = Textus::Entry.for_format(entry.format).extensions.first
+                 File.join(@root, "zones", entry.path, *remaining) + primary_ext
+               end
         [entry, path, remaining]
       end
     end
@@ -96,39 +100,11 @@ module Textus
 
     # Enumerate all entry files reachable through the manifest. Returns
     # [{ key:, path:, manifest_entry: }, ...]
-    # rubocop:disable Metrics/AbcSize
     def enumerate(prefix: nil)
-      out = []
-      @entries.each do |entry|
-        if entry.nested
-          base = File.join(@root, "zones", entry.path)
-          next unless File.directory?(base)
-
-          glob_pattern = nested_glob(entry.format)
-          Dir.glob(File.join(base, glob_pattern)).each do |fp|
-            rel = fp.sub(%r{\A#{Regexp.escape(base)}/?}, "")
-            stripped = rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
-            segs = stripped.split("/").reject(&:empty?)
-            next if segs.empty?
-
-            illegal = segs.find { |s| !valid_segment?(s) }
-            if illegal
-              warn("textus: skipping illegal key segment '#{illegal}' at #{fp} — run 'textus key migrate --dry-run'")
-              next
-            end
-
-            full_key = (entry.key.split(".") + segs).join(".")
-            out << { key: full_key, path: fp, manifest_entry: entry }
-          end
-        else
-          fp = resolve_leaf_path(entry)
-          out << { key: entry.key, path: fp, manifest_entry: entry } if File.exist?(fp)
-        end
-      end
+      out = @entries.flat_map { |entry| entry.nested ? enumerate_nested(entry) : enumerate_leaf(entry) }
       out.select! { |row| row[:key] == prefix || row[:key].start_with?("#{prefix}.") } if prefix
       out.sort_by { |row| row[:key] }
     end
-    # rubocop:enable Metrics/AbcSize
 
     def validate_key!(key)
       raise UsageError.new("empty key") if key.nil? || key.empty?
@@ -138,6 +114,34 @@ module Textus
 
     private
 
+    def enumerate_leaf(entry)
+      fp = resolve_leaf_path(entry)
+      File.exist?(fp) ? [{ key: entry.key, path: fp, manifest_entry: entry }] : []
+    end
+
+    def enumerate_nested(entry)
+      base = File.join(@root, "zones", entry.path)
+      return [] unless File.directory?(base)
+
+      glob_pattern = entry.index_filename ? "**/#{entry.index_filename}" : nested_glob(entry.format)
+      Dir.glob(File.join(base, glob_pattern)).filter_map { |path| nested_row_for(entry, base, path) }
+    end
+
+    def nested_row_for(entry, base, path)
+      rel = path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+      stripped = entry.index_filename ? File.dirname(rel) : rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
+      segs = stripped.split("/").reject { |s| s.empty? || s == "." }
+      return nil if segs.empty?
+
+      illegal = segs.find { |s| !valid_segment?(s) }
+      if illegal
+        warn("textus: skipping illegal key segment '#{illegal}' at #{path} — run 'textus key migrate --dry-run'")
+        return nil
+      end
+
+      { key: (entry.key.split(".") + segs).join("."), path: path, manifest_entry: entry }
+    end
+
     def valid_segment?(seg)
       return false if seg.nil? || seg.empty?
       return false if seg.length > Key::Grammar::MAX_SEGMENT_LEN

data/lib/textus/store/mover.rb

@@ -2,8 +2,12 @@ require "fileutils"
 
 module Textus
   class Store
-    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     class Mover
+      MovePlan = Data.define(
+        :old_key, :new_key, :old_path, :new_path,
+        :new_mentry, :uid, :etag_before, :as
+      )
+
       def initialize(store:, reader:, writer:, manifest:, audit_log:)
         @store = store
         @reader = reader
@@ -13,6 +17,22 @@ module Textus
       end
 
       def call(old_key, new_key, as: Role::DEFAULT, dry_run: false, correlation_id: nil)
+        plan, pre_env = prepare_plan(old_key, new_key, as: as)
+        return dry_run_result(plan) if dry_run
+
+        plan = ensure_uid!(plan, pre_env: pre_env)
+        etag_after = perform_move!(plan)
+        new_envelope = record_move(plan, etag_after: etag_after, correlation_id: correlation_id)
+        success_result(plan, new_envelope: new_envelope)
+      end
+
+      private
+
+      # Validates inputs, resolves manifest entries, and reads the source
+      # envelope. Returns [MovePlan, pre_envelope]; the pre_envelope is only
+      # needed by ensure_uid! and is threaded separately to keep MovePlan
+      # focused on the planned operation.
+      def prepare_plan(old_key, new_key, as:)
         @manifest.validate_key!(old_key)
         @manifest.validate_key!(new_key)
         raise UsageError.new("mv: old and new keys are identical") if old_key == new_key
@@ -21,81 +41,103 @@ module Textus
         raise UnknownKey.new(old_key) unless File.exist?(old_path)
 
         new_mentry, new_path, = @manifest.resolve(new_key)
+        validate_zone_and_format!(old_mentry, new_mentry)
+        validate_writer!(old_mentry, old_key, as)
+        raise UsageError.new("mv: target '#{new_key}' already exists at #{new_path}") if File.exist?(new_path)
 
+        pre_env = @reader.get(old_key)
+        plan = MovePlan.new(
+          old_key: old_key, new_key: new_key,
+          old_path: old_path, new_path: new_path,
+          new_mentry: new_mentry,
+          uid: pre_env["uid"], etag_before: pre_env["etag"], as: as
+        )
+        [plan, pre_env]
+      end
+
+      def validate_zone_and_format!(old_mentry, new_mentry)
         if old_mentry.zone != new_mentry.zone
           raise UsageError.new(
             "mv: cross-zone move refused (#{old_mentry.zone} → #{new_mentry.zone}). " \
             "Use put+delete for cross-zone moves.",
           )
         end
-        if old_mentry.format != new_mentry.format
-          raise UsageError.new(
-            "mv: format mismatch (#{old_mentry.format} → #{new_mentry.format}); refusing.",
-          )
-        end
+        return if old_mentry.format == new_mentry.format
 
-        writers = @manifest.zone_writers(old_mentry.zone)
-        raise WriteForbidden.new(old_key, old_mentry.zone, writers: writers) unless writers.include?(as)
+        raise UsageError.new(
+          "mv: format mismatch (#{old_mentry.format} → #{new_mentry.format}); refusing.",
+        )
+      end
 
-        raise UsageError.new("mv: target '#{new_key}' already exists at #{new_path}") if File.exist?(new_path)
+      def validate_writer!(mentry, key, as)
+        writers = @manifest.zone_writers(mentry.zone)
+        return if writers.include?(as)
 
-        # Mint uid before the move so the audit row carries it.
-        pre_env = @reader.get(old_key)
-        current_uid = pre_env["uid"]
-        etag_before = pre_env["etag"]
-
-        if dry_run
-          return {
-            "protocol" => PROTOCOL, "ok" => true, "dry_run" => true,
-            "from_key" => old_key, "to_key" => new_key,
-            "from_path" => old_path, "to_path" => new_path,
-            "uid" => current_uid
-          }
-        end
+        raise WriteForbidden.new(key, mentry.zone, writers: writers)
+      end
 
-        if current_uid.nil?
-          # Write the uid in place first so the source file carries it before mv.
-          pre_env = @writer.put(old_key,
-                                meta: pre_env["_meta"],
-                                body: pre_env["body"],
-                                content: pre_env["content"],
-                                as: as,
-                                suppress_events: true)
-          current_uid = pre_env["uid"]
-          etag_before = pre_env["etag"]
-        end
+      def ensure_uid!(plan, pre_env:)
+        return plan if plan.uid
 
-        FileUtils.mkdir_p(File.dirname(new_path))
-        FileUtils.mv(old_path, new_path)
-        rewrite_name_for_mv!(new_mentry, new_path, new_key)
-        etag_after = Etag.for_file(new_path)
+        env = @writer.put(
+          plan.old_key,
+          meta: pre_env["_meta"],
+          body: pre_env["body"],
+          content: pre_env["content"],
+          as: plan.as,
+          suppress_events: true,
+        )
+        plan.with(uid: env["uid"], etag_before: env["etag"])
+      end
+
+      def perform_move!(plan)
+        FileUtils.mkdir_p(File.dirname(plan.new_path))
+        FileUtils.mv(plan.old_path, plan.new_path)
+        rewrite_name_for_mv!(plan.new_mentry, plan.new_path, plan.new_key)
+        Etag.for_file(plan.new_path)
+      end
 
+      def record_move(plan, etag_after:, correlation_id:)
         extras = {
-          "from_key" => old_key, "to_key" => new_key,
-          "from_path" => old_path, "to_path" => new_path,
-          "uid" => current_uid
+          "from_key" => plan.old_key, "to_key" => plan.new_key,
+          "from_path" => plan.old_path, "to_path" => plan.new_path,
+          "uid" => plan.uid
         }
         extras["correlation_id"] = correlation_id if correlation_id
 
         @audit_log.append(
-          role: as, verb: "mv", key: new_key,
-          etag_before: etag_before, etag_after: etag_after,
+          role: plan.as, verb: "mv", key: plan.new_key,
+          etag_before: plan.etag_before, etag_after: etag_after,
           extras: extras
         )
+        new_envelope = @reader.get(plan.new_key)
+        @store.fire_event(
+          :mv,
+          key: plan.new_key, from_key: plan.old_key, to_key: plan.new_key,
+          envelope: new_envelope
+        )
+        new_envelope
+      end
+
+      def dry_run_result(plan)
+        {
+          "protocol" => PROTOCOL, "ok" => true, "dry_run" => true,
+          "from_key" => plan.old_key, "to_key" => plan.new_key,
+          "from_path" => plan.old_path, "to_path" => plan.new_path,
+          "uid" => plan.uid
+        }
+      end
 
-        new_envelope = @reader.get(new_key)
-        @store.fire_event(:mv, key: new_key, from_key: old_key, to_key: new_key, envelope: new_envelope)
+      def success_result(plan, new_envelope:)
         {
           "protocol" => PROTOCOL, "ok" => true,
-          "from_key" => old_key, "to_key" => new_key,
-          "from_path" => old_path, "to_path" => new_path,
-          "uid" => current_uid,
+          "from_key" => plan.old_key, "to_key" => plan.new_key,
+          "from_path" => plan.old_path, "to_path" => plan.new_path,
+          "uid" => plan.uid,
           "envelope" => new_envelope
         }
       end
 
-      private
-
       # If the moved file carries a `name:` field (markdown) or `_meta.name`
       # (json/yaml), rewrite it to the new basename so enforce_name_match! stays
       # happy on the next read. Only touches the bytes when name actually changes.
@@ -121,6 +163,5 @@ module Textus
         end
       end
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
   end
 end

data/lib/textus/store/staleness/generator_check.rb

@@ -0,0 +1,88 @@
+require "time"
+
+module Textus
+  class Store
+    class Staleness
+      # Reports staleness for generator-zone entries — derived files whose
+      # generator's listed sources have been modified more recently than the
+      # entry's `_meta.generated.at` timestamp. Returns an Array of row hashes
+      # (possibly empty) per entry.
+      class GeneratorCheck
+        def initialize(manifest:)
+          @manifest = manifest
+        end
+
+        def rows_for(mentry)
+          return [] unless mentry.in_generator_zone?
+
+          gen = mentry.generator
+          return [] unless gen
+
+          path = Textus::Key::Path.resolve(@manifest, mentry)
+          return [stale_row(mentry, path, "derived entry has never been generated")] unless File.exist?(path)
+
+          parsed = Entry.for_format(mentry.format).parse(File.binread(path), path: path)
+          generated_at = parsed["_meta"].dig("generated", "at")
+          return [stale_row(mentry, path, "missing generated.at frontmatter")] unless generated_at
+
+          gen_time = parse_time(generated_at)
+          return [stale_row(mentry, path, "unparseable generated.at: #{generated_at.inspect}")] unless gen_time
+
+          offender = newest_source_after(gen, gen_time)
+          return [stale_row(mentry, path, "source '#{offender}' modified after generated.at")] if offender
+
+          []
+        end
+
+        private
+
+        def parse_time(str)
+          Time.parse(str.to_s)
+        rescue StandardError
+          nil
+        end
+
+        def newest_source_after(gen, gen_time)
+          Array(gen["sources"]).each do |src|
+            offender = check_source(src, gen_time)
+            return offender if offender
+          end
+          nil
+        end
+
+        def check_source(src, gen_time)
+          if src.match?(/\A[a-z0-9.][a-z0-9._-]*\z/) && !src.include?("/")
+            @manifest.enumerate(prefix: src).each do |row|
+              return src if File.mtime(row[:path]) > gen_time
+            end
+            nil
+          else
+            check_filesystem_source(src, gen_time)
+          end
+        end
+
+        def check_filesystem_source(src, gen_time)
+          abs = File.absolute_path?(src) ? src : File.join(File.dirname(@manifest.root), src)
+          if File.directory?(abs)
+            Dir.glob(File.join(abs, "**", "*")).each do |fp|
+              next unless File.file?(fp)
+              return src if File.mtime(fp) > gen_time
+            end
+            nil
+          elsif File.exist?(abs) && File.mtime(abs) > gen_time
+            src
+          end
+        end
+
+        def stale_row(mentry, path, reason)
+          {
+            "key" => mentry.key,
+            "path" => path,
+            "generator" => mentry.generator,
+            "reason" => reason,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/store/staleness/intake_check.rb

@@ -0,0 +1,46 @@
+require "time"
+
+module Textus
+  class Store
+    class Staleness
+      # Reports TTL-exceeded staleness for intake-handler entries. Returns an
+      # Array of row hashes (possibly empty) per entry.
+      class IntakeCheck
+        def initialize(manifest:)
+          @manifest = manifest
+        end
+
+        def rows_for(mentry)
+          return [] unless mentry.intake_handler
+
+          ttl = @manifest.policies_for(mentry.key).refresh&.ttl_seconds
+          return [] unless ttl
+
+          path = Textus::Key::Path.resolve(@manifest, mentry)
+          return [row(mentry, path, "never refreshed")] unless File.exist?(path)
+
+          meta = Entry.for_format(mentry.format).parse(File.binread(path), path: path)["_meta"]
+          last_str = meta["last_refreshed_at"]
+          return [row(mentry, path, "never refreshed (no last_refreshed_at)")] if last_str.nil?
+
+          last = parse_time(last_str)
+          return [row(mentry, path, "ttl exceeded (#{ttl}s)")] if last.nil? || (Time.now - last) > ttl
+
+          []
+        end
+
+        private
+
+        def parse_time(str)
+          Time.parse(str.to_s)
+        rescue StandardError
+          nil
+        end
+
+        def row(mentry, path, reason)
+          { "key" => mentry.key, "path" => path, "handler" => mentry.intake_handler, "reason" => reason }
+        end
+      end
+    end
+  end
+end

data/lib/textus/store/staleness.rb

@@ -1,121 +1,26 @@
-require "time"
-
 module Textus
   class Store
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/BlockLength
     class Staleness
       def initialize(manifest:)
         @manifest = manifest
+        @generator_check = GeneratorCheck.new(manifest: manifest)
+        @intake_check = IntakeCheck.new(manifest: manifest)
       end
 
       def call(prefix: nil, zone: nil)
-        out = []
-        @manifest.entries.each do |mentry|
-          next unless mentry.in_generator_zone?
-          next if zone && mentry.zone != zone
-
-          gen = mentry.generator
-          next unless gen
-          next if prefix && !(mentry.key == prefix || mentry.key.start_with?("#{prefix}."))
-
-          path = Textus::Key::Path.resolve(@manifest, mentry)
-
-          unless File.exist?(path)
-            out << stale_row(mentry, path, "derived entry has never been generated")
-            next
-          end
-
-          raw = File.binread(path)
-          parsed = Entry.for_format(mentry.format).parse(raw, path: path)
-          generated_at = parsed["_meta"].dig("generated", "at")
-          unless generated_at
-            out << stale_row(mentry, path, "missing generated.at frontmatter")
-            next
-          end
-          gen_time = begin
-            Time.parse(generated_at.to_s)
-          rescue StandardError
-            nil
-          end
-          unless gen_time
-            out << stale_row(mentry, path, "unparseable generated.at: #{generated_at.inspect}")
-            next
-          end
-
-          offender = newest_source_after(gen, gen_time)
-          out << stale_row(mentry, path, "source '#{offender}' modified after generated.at") if offender
-        end
-
-        @manifest.entries.each do |mentry|
-          next unless mentry.intake_handler
-          next if zone && mentry.zone != zone
-          next if prefix && !(mentry.key == prefix || mentry.key.start_with?("#{prefix}."))
-
-          policy_set = @manifest.policies_for(mentry.key)
-          ttl = policy_set.refresh&.ttl_seconds
-          next unless ttl
-
-          path = Textus::Key::Path.resolve(@manifest, mentry)
-
-          unless File.exist?(path)
-            out << intake_stale_row(mentry, path, "never refreshed")
-            next
-          end
-
-          meta = Entry.for_format(mentry.format).parse(File.binread(path), path: path)["_meta"]
-          last_str = meta["last_refreshed_at"]
-          if last_str.nil?
-            out << intake_stale_row(mentry, path, "never refreshed (no last_refreshed_at)")
-            next
-          end
-
-          last = begin
-            Time.parse(last_str.to_s)
-          rescue StandardError
-            nil
-          end
-          out << intake_stale_row(mentry, path, "ttl exceeded (#{ttl}s)") if last.nil? || (Time.now - last) > ttl
-        end
-
-        out
+        @manifest.entries
+                 .select { |m| entry_matches?(m, prefix: prefix, zone: zone) }
+                 .flat_map { |m| @generator_check.rows_for(m) + @intake_check.rows_for(m) }
       end
 
       private
 
-      def newest_source_after(gen, gen_time)
-        Array(gen["sources"]).each do |src|
-          if src.match?(/\A[a-z0-9.][a-z0-9._-]*\z/) && !src.include?("/")
-            @manifest.enumerate(prefix: src).each do |row|
-              return src if File.mtime(row[:path]) > gen_time
-            end
-          else
-            abs = File.absolute_path?(src) ? src : File.join(File.dirname(@manifest.root), src)
-            if File.directory?(abs)
-              Dir.glob(File.join(abs, "**", "*")).each do |fp|
-                next unless File.file?(fp)
-                return src if File.mtime(fp) > gen_time
-              end
-            elsif File.exist?(abs)
-              return src if File.mtime(abs) > gen_time
-            end
-          end
-        end
-        nil
-      end
-
-      def intake_stale_row(mentry, path, reason)
-        { "key" => mentry.key, "path" => path, "handler" => mentry.intake_handler, "reason" => reason }
-      end
+      def entry_matches?(mentry, prefix:, zone:)
+        return false if zone && mentry.zone != zone
+        return false if prefix && !(mentry.key == prefix || mentry.key.start_with?("#{prefix}."))
 
-      def stale_row(mentry, path, reason)
-        {
-          "key" => mentry.key,
-          "path" => path,
-          "generator" => mentry.generator,
-          "reason" => reason,
-        }
+        true
       end
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/BlockLength
   end
 end

data/lib/textus/store/writer.rb

@@ -2,8 +2,9 @@ require "fileutils"
 
 module Textus
   class Store
-    # rubocop:disable Metrics/ParameterLists
     class Writer
+      Payload = Data.define(:meta, :body, :content)
+
       def initialize(store)
         @store = store
         @manifest = store.manifest
@@ -11,28 +12,30 @@ module Textus
       end
 
       # Backward-compat shim — orchestration now lives in Application::Writes::Put.
+      # rubocop:disable Metrics/ParameterLists
       def put(key, meta: nil, body: nil, content: nil, if_etag: nil, as: Role::DEFAULT, suppress_events: false)
         ctx = Textus::Application::Context.new(store: @store, role: as)
         Textus::Application::Writes::Put.new(ctx: ctx, bus: @store.bus).call(
           key, meta: meta, body: body, content: content, if_etag: if_etag, suppress_events: suppress_events
         )
       end
+      # rubocop:enable Metrics/ParameterLists
 
       # Pure I/O: validate, serialize, etag-check, write to disk, audit. No
       # permission check and no event firing — those are handled by the caller
       # (Application::Writes::Put).
-      def write_envelope_to_disk(key, mentry:, meta: nil, body: nil, content: nil, if_etag: nil, as: Role::DEFAULT, correlation_id: nil)
+      def write_envelope_to_disk(key, mentry:, payload:, ctx:, if_etag: nil)
         _, path, = @manifest.resolve(key)
 
-        meta ||= {}
+        meta = payload.meta || {}
         strategy = Entry.for_format(mentry.format)
 
         existing_uid = existing_uid_for(mentry, path)
-        meta, content = ensure_uid(mentry.format, meta, content, existing_uid)
+        meta, content = ensure_uid(mentry.format, meta, payload.content, existing_uid)
 
         bytes, eff_meta, eff_body, eff_content = serialize_for_put(
           mentry: mentry, path: path, strategy: strategy,
-          meta: meta, body: body, content: content
+          meta: meta, body: payload.body, content: content
         )
 
         enforce_name_match!(path, eff_meta, mentry.format)
@@ -52,9 +55,9 @@ module Textus
         File.binwrite(path, bytes)
         etag_after = Etag.for_bytes(bytes)
         @store.audit_log.append(
-          role: as, verb: "put", key: key,
+          role: ctx.role, verb: "put", key: key,
           etag_before: etag_before, etag_after: etag_after,
-          extras: correlation_id ? { "correlation_id" => correlation_id } : nil
+          extras: ctx.correlation_id ? { "correlation_id" => ctx.correlation_id } : nil
         )
         Envelope.build(
           key: key, mentry: mentry, path: path,
@@ -129,7 +132,7 @@ module Textus
       # Pure I/O: resolve path, validate etag, delete from disk, audit. No
       # permission check and no event firing — those are handled by the caller
       # (Application::Writes::Delete).
-      def delete_envelope_from_disk(key, if_etag: nil, as: Role::DEFAULT, correlation_id: nil)
+      def delete_envelope_from_disk(key, ctx:, if_etag: nil)
         _, path, = @manifest.resolve(key)
         raise UnknownKey.new(key, suggestions: @manifest.suggestions_for(key)) unless File.exist?(path)
 
@@ -138,9 +141,9 @@ module Textus
 
         File.delete(path)
         @store.audit_log.append(
-          role: as, verb: "delete", key: key,
+          role: ctx.role, verb: "delete", key: key,
           etag_before: etag_before, etag_after: nil,
-          extras: correlation_id ? { "correlation_id" => correlation_id } : nil
+          extras: ctx.correlation_id ? { "correlation_id" => ctx.correlation_id } : nil
         )
       end
 
@@ -164,6 +167,5 @@ module Textus
         { "protocol" => PROTOCOL, "rejected" => pending_key, "target_key" => target_key }
       end
     end
-    # rubocop:enable Metrics/ParameterLists
   end
 end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.10.4"
+  VERSION = "0.10.5"
   PROTOCOL = "textus/2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.10.4
+  version: 0.10.5
 platform: ruby
 authors:
 - Patrick
@@ -235,6 +235,8 @@ files:
 - lib/textus/store/reader.rb
 - lib/textus/store/sentinel.rb
 - lib/textus/store/staleness.rb
+- lib/textus/store/staleness/generator_check.rb
+- lib/textus/store/staleness/intake_check.rb
 - lib/textus/store/validator.rb
 - lib/textus/store/writer.rb
 - lib/textus/version.rb