textus 0.53.0 → 0.54.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (160) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +52 -0
  3. data/README.md +53 -73
  4. data/SPEC.md +2 -5
  5. data/docs/architecture/README.md +149 -159
  6. data/lib/textus/action/accept.rb +0 -9
  7. data/lib/textus/action/audit.rb +0 -2
  8. data/lib/textus/action/blame.rb +0 -2
  9. data/lib/textus/action/boot.rb +2 -11
  10. data/lib/textus/action/data_mv.rb +1 -3
  11. data/lib/textus/action/deps.rb +1 -15
  12. data/lib/textus/action/doctor.rb +0 -2
  13. data/lib/textus/action/drain.rb +4 -6
  14. data/lib/textus/action/enqueue.rb +3 -5
  15. data/lib/textus/action/get.rb +1 -3
  16. data/lib/textus/action/ingest.rb +135 -0
  17. data/lib/textus/action/jobs.rb +1 -3
  18. data/lib/textus/action/key_delete.rb +0 -10
  19. data/lib/textus/action/key_delete_prefix.rb +1 -3
  20. data/lib/textus/action/key_mv.rb +1 -15
  21. data/lib/textus/action/key_mv_prefix.rb +1 -3
  22. data/lib/textus/action/list.rb +0 -2
  23. data/lib/textus/action/propose.rb +0 -2
  24. data/lib/textus/action/published.rb +0 -2
  25. data/lib/textus/action/pulse.rb +7 -38
  26. data/lib/textus/action/put.rb +1 -12
  27. data/lib/textus/action/rdeps.rb +2 -12
  28. data/lib/textus/action/reject.rb +0 -12
  29. data/lib/textus/action/rule_explain.rb +0 -4
  30. data/lib/textus/action/rule_lint.rb +1 -3
  31. data/lib/textus/action/rule_list.rb +0 -4
  32. data/lib/textus/action/schema_envelope.rb +0 -2
  33. data/lib/textus/action/uid.rb +0 -2
  34. data/lib/textus/action/where.rb +0 -2
  35. data/lib/textus/action/write_verb.rb +4 -18
  36. data/lib/textus/boot.rb +40 -109
  37. data/lib/textus/command.rb +6 -1
  38. data/lib/textus/container.rb +21 -5
  39. data/lib/textus/core/freshness/evaluator.rb +18 -34
  40. data/lib/textus/core/freshness/verdict.rb +1 -1
  41. data/lib/textus/doctor/check/notebook_sources.rb +50 -0
  42. data/lib/textus/doctor/check/protocol_version.rb +6 -6
  43. data/lib/textus/doctor/check/raw_asset_paths.rb +50 -0
  44. data/lib/textus/doctor/check/stale_reviewed_stamp.rb +54 -0
  45. data/lib/textus/doctor/check.rb +0 -1
  46. data/lib/textus/doctor.rb +3 -42
  47. data/lib/textus/envelope/reader.rb +46 -0
  48. data/lib/textus/envelope/writer.rb +209 -0
  49. data/lib/textus/envelope.rb +19 -6
  50. data/lib/textus/errors.rb +9 -5
  51. data/lib/textus/{entry → format}/base.rb +1 -6
  52. data/lib/textus/{entry → format}/json.rb +1 -4
  53. data/lib/textus/{entry → format}/markdown.rb +2 -6
  54. data/lib/textus/{entry → format}/text.rb +2 -6
  55. data/lib/textus/{entry → format}/yaml.rb +1 -4
  56. data/lib/textus/{entry.rb → format.rb} +9 -10
  57. data/lib/textus/gate/auth.rb +58 -12
  58. data/lib/textus/gate.rb +2 -0
  59. data/lib/textus/init.rb +16 -79
  60. data/lib/textus/jobs/base.rb +23 -0
  61. data/lib/textus/jobs/materialize.rb +20 -0
  62. data/lib/textus/{background → jobs}/plan.rb +1 -1
  63. data/lib/textus/jobs/planner.rb +101 -0
  64. data/lib/textus/jobs/retention.rb +48 -0
  65. data/lib/textus/jobs/sweep.rb +27 -0
  66. data/lib/textus/{background → jobs}/worker.rb +2 -2
  67. data/lib/textus/jobs.rb +15 -0
  68. data/lib/textus/key/path.rb +1 -1
  69. data/lib/textus/manifest/entry/base.rb +4 -19
  70. data/lib/textus/manifest/entry/parser.rb +27 -10
  71. data/lib/textus/manifest/entry/produced.rb +13 -34
  72. data/lib/textus/manifest/entry/publish/to_paths.rb +4 -4
  73. data/lib/textus/manifest/entry/publish.rb +0 -12
  74. data/lib/textus/manifest/entry/validators/format_matrix.rb +1 -1
  75. data/lib/textus/manifest/entry/validators.rb +0 -1
  76. data/lib/textus/manifest/policy/source.rb +14 -62
  77. data/lib/textus/manifest/policy.rb +2 -5
  78. data/lib/textus/manifest/resolver.rb +2 -2
  79. data/lib/textus/manifest/schema/contract.rb +61 -0
  80. data/lib/textus/manifest/schema/keys.rb +6 -20
  81. data/lib/textus/manifest/schema/semantics.rb +232 -0
  82. data/lib/textus/manifest/schema/validator.rb +24 -302
  83. data/lib/textus/manifest/schema/vocabulary.rb +1 -0
  84. data/lib/textus/manifest/schema.rb +1 -4
  85. data/lib/textus/manifest.rb +1 -3
  86. data/lib/textus/ports/{queue → job_store}/job.rb +1 -1
  87. data/lib/textus/ports/{queue.rb → job_store.rb} +6 -13
  88. data/lib/textus/produce/engine.rb +50 -0
  89. data/lib/textus/produce/render.rb +20 -0
  90. data/lib/textus/session.rb +15 -8
  91. data/lib/textus/store.rb +5 -14
  92. data/lib/textus/surfaces/mcp/catalog.rb +23 -11
  93. data/lib/textus/surfaces/mcp/errors.rb +0 -9
  94. data/lib/textus/surfaces/mcp/server.rb +87 -110
  95. data/lib/textus/surfaces/role_scope.rb +0 -4
  96. data/lib/textus/surfaces/watcher.rb +3 -3
  97. data/lib/textus/types.rb +15 -0
  98. data/lib/textus/version.rb +2 -2
  99. data/lib/textus/workflow/collector.rb +27 -0
  100. data/lib/textus/workflow/context.rb +5 -0
  101. data/lib/textus/workflow/dsl.rb +44 -0
  102. data/lib/textus/workflow/loader.rb +17 -0
  103. data/lib/textus/workflow/pattern.rb +18 -0
  104. data/lib/textus/workflow/registry.rb +21 -0
  105. data/lib/textus/workflow/runner.rb +99 -0
  106. data/lib/textus/workflow.rb +28 -0
  107. data/lib/textus.rb +12 -1
  108. metadata +67 -66
  109. data/lib/textus/action/pulse/scanner.rb +0 -118
  110. data/lib/textus/background/job/base.rb +0 -27
  111. data/lib/textus/background/job/materialize.rb +0 -31
  112. data/lib/textus/background/job/refresh.rb +0 -22
  113. data/lib/textus/background/job/sweep.rb +0 -31
  114. data/lib/textus/background/job.rb +0 -19
  115. data/lib/textus/background/planner/plan.rb +0 -113
  116. data/lib/textus/background/retention/apply.rb +0 -50
  117. data/lib/textus/doctor/check/handler_permit.rb +0 -34
  118. data/lib/textus/doctor/check/hooks.rb +0 -25
  119. data/lib/textus/doctor/check/intake_registration.rb +0 -46
  120. data/lib/textus/envelope/io/reader.rb +0 -48
  121. data/lib/textus/envelope/io/writer.rb +0 -211
  122. data/lib/textus/events.rb +0 -21
  123. data/lib/textus/init/templates/machine_intake.rb +0 -49
  124. data/lib/textus/init/templates/orientation_reducer.rb +0 -21
  125. data/lib/textus/manifest/entry/validators/events.rb +0 -22
  126. data/lib/textus/manifest/policy/handler_permit.rb +0 -17
  127. data/lib/textus/pipeline/acquire/handler.rb +0 -29
  128. data/lib/textus/pipeline/acquire/intake.rb +0 -132
  129. data/lib/textus/pipeline/acquire/projection.rb +0 -129
  130. data/lib/textus/pipeline/acquire/serializer/json.rb +0 -31
  131. data/lib/textus/pipeline/acquire/serializer/text.rb +0 -16
  132. data/lib/textus/pipeline/acquire/serializer/yaml.rb +0 -31
  133. data/lib/textus/pipeline/acquire/serializer.rb +0 -17
  134. data/lib/textus/pipeline/engine.rb +0 -97
  135. data/lib/textus/pipeline/render.rb +0 -25
  136. data/lib/textus/ports/audit_subscriber.rb +0 -42
  137. data/lib/textus/projection.rb +0 -103
  138. data/lib/textus/step/base.rb +0 -35
  139. data/lib/textus/step/builtin/csv_fetch.rb +0 -19
  140. data/lib/textus/step/builtin/ical_events_fetch.rb +0 -30
  141. data/lib/textus/step/builtin/json_fetch.rb +0 -18
  142. data/lib/textus/step/builtin/markdown_links_fetch.rb +0 -20
  143. data/lib/textus/step/builtin/rss_fetch.rb +0 -26
  144. data/lib/textus/step/builtin.rb +0 -22
  145. data/lib/textus/step/catalog.rb +0 -37
  146. data/lib/textus/step/context.rb +0 -74
  147. data/lib/textus/step/discovery.rb +0 -24
  148. data/lib/textus/step/error_log.rb +0 -32
  149. data/lib/textus/step/event_bus.rb +0 -113
  150. data/lib/textus/step/fetch.rb +0 -13
  151. data/lib/textus/step/fire_report.rb +0 -23
  152. data/lib/textus/step/loader.rb +0 -108
  153. data/lib/textus/step/observe.rb +0 -31
  154. data/lib/textus/step/registry_store.rb +0 -66
  155. data/lib/textus/step/signature.rb +0 -31
  156. data/lib/textus/step/transform.rb +0 -12
  157. data/lib/textus/step/validate.rb +0 -11
  158. data/lib/textus/step.rb +0 -10
  159. data/lib/textus/surfaces/mcp/session.rb +0 -9
  160. data/lib/textus/surfaces/mcp/tool_schemas.rb +0 -17
@@ -1,324 +1,46 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module Textus
2
4
  class Manifest
3
5
  module Schema
4
- # The manifest validation walk. Extracted from Schema (ADR 0107); the
5
- # schema data now lives in Schema::Vocabulary (coordination vocabulary,
6
- # LANES + derived) and Schema::Keys (key whitelists / FIELD_REGISTRY),
7
- # re-exported on Schema — while the validation *logic* lives here.
8
- # Lexically nested under Schema, so bare constant references
9
- # (ROOT_KEYS, LANES, FIELD_REGISTRY, …) resolve to Schema's constants.
6
+ # Orchestrates structural validation (dry-schema Contract) then cross-field
7
+ # semantic checks (Semantics). Public interface unchanged: Validator.validate!(raw).
10
8
  module Validator
11
9
  module_function
12
10
 
13
11
  def validate!(raw)
14
12
  raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
15
13
 
16
- walk(raw, ROOT_KEYS, "$")
17
- raise BadManifest.new("manifest must declare lanes:") if Array(raw["lanes"]).empty?
18
-
19
- validate_roles!(raw["roles"])
20
- validate_lanes!(raw["lanes"])
21
- validate_entries!(raw["entries"])
22
- validate_owners!(raw["lanes"], raw["entries"])
23
- validate_rules!(raw["rules"])
24
- walk(raw["audit"], AUDIT_KEYS, "$.audit") if raw["audit"].is_a?(Hash)
25
- validate_single_queue!(raw)
26
- validate_single_machine!(raw)
27
- validate_lane_kind_consistency!(raw)
28
- end
29
-
30
- def validate_lanes!(lanes)
31
- Array(lanes).each_with_index do |z, i|
32
- walk(z, LANE_KEYS, "$.lanes[#{i}]")
33
- if z["kind"].nil?
34
- raise BadManifest.new("lane '#{z["name"]}' at '$.lanes[#{i}]' must declare a kind (one of: #{LANE_KINDS.join(", ")})")
35
- end
36
- next if LANE_KINDS.include?(z["kind"])
37
-
38
- if %w[quarantine derived].include?(z["kind"])
39
- raise BadManifest.new(
40
- "lane kind '#{z["kind"]}' at '$.lanes[#{i}]' was folded into 'machine' (ADR 0091) — " \
41
- "use `kind: machine`",
42
- )
43
- end
44
-
45
- raise BadManifest.new(
46
- "unknown lane kind '#{z["kind"]}' at '$.lanes[#{i}]' (known: #{LANE_KINDS.join(", ")})",
47
- )
48
- end
49
- end
50
-
51
- def validate_entries!(entries)
52
- Array(entries).each_with_index do |e, i|
53
- path = "$.entries[#{i}]"
54
- reject_retired_publish_keys!(e, path)
55
- reject_retired_render_keys!(e, path)
56
- walk(e, ENTRY_KEYS, path)
57
- validate_publish_block!(e, path)
58
- walk(e["source"], SOURCE_KEYS, "#{path}.source") if e["source"]
59
- end
60
- end
61
-
62
- # Retired keys are no longer allowed, so `walk` would reject them as merely
63
- # "unknown"; intercept first with the migration path so a pre-0.43 manifest
64
- # gets a useful error. `publish_each` was removed (ADR 0051); `publish_to`/
65
- # `publish_tree` were folded into the `publish:` block (ADR 0052);
66
- # `index_filename` was removed (ADR 0053).
67
- def reject_retired_publish_keys!(entry, path)
68
- return unless entry.is_a?(Hash)
69
-
70
- if entry.key?("publish_each")
71
- raise BadManifest.new(
72
- "publish_each was removed in 0.42.0 (ADR 0051) at '#{path}' — " \
73
- "mirror the subtree with `publish: { tree: \"...\" }`.",
74
- )
75
- end
76
-
77
- if entry.key?("publish_to")
78
- raise BadManifest.new(
79
- "publish_to was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
80
- "use `publish: { to: [...] }`.",
81
- )
82
- end
83
-
84
- if entry.key?("publish_tree")
85
- raise BadManifest.new(
86
- "publish_tree was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
87
- "use `publish: { tree: \"...\" }`.",
88
- )
89
- end
90
-
91
- return unless entry.key?("index_filename")
92
-
93
- raise BadManifest.new(
94
- "index_filename was removed in 0.43.0 (ADR 0053) at '#{path}' — a nested entry now enumerates " \
95
- "each file as a key; to mirror a directory of files to a consumer path use `publish: { tree: \"...\" }`.",
96
- )
97
- end
98
-
99
- # ADR 0094: rendering is a publish concern. An entry no longer
100
- # declares a build-time template or render flags — they move onto publish
101
- # targets. Provenance lives in the data's `_meta`, not a flag.
102
- def reject_retired_render_keys!(entry, path)
103
- return unless entry.is_a?(Hash)
104
-
105
- if entry.key?("template")
106
- raise BadManifest.new(
107
- "entry-level `template:` was removed at '#{path}' (ADR 0094): rendering is a " \
108
- "publish concern — `publish: [{ to:, template: }]`.",
109
- )
110
- end
111
- if entry.key?("inject_boot")
112
- raise BadManifest.new(
113
- "entry-level `inject_boot:` was removed at '#{path}' (ADR 0094): it is a render " \
114
- "flag — `publish: [{ to:, inject_boot: }]`.",
115
- )
116
- end
117
- return unless entry.key?("provenance")
118
-
119
- raise BadManifest.new("entry-level `provenance:` was removed at '#{path}' (ADR 0094): provenance lives in the data's `_meta`.")
120
- end
121
-
122
- # ADR 0094: publish is a LIST of target objects. The old
123
- # `{ to: [...] }` / `{ tree: … }` map forms are retired (fold hint).
124
- def validate_publish_block!(entry, path)
125
- return unless entry.is_a?(Hash) && entry.key?("publish")
126
-
127
- block = entry["publish"]
128
- if block.is_a?(Hash)
129
- raise BadManifest.new(
130
- "publish: at '#{path}.publish' must be a list of targets " \
131
- "[{ to:, template:? } | { tree: }] (ADR 0094); the map form was retired.",
132
- )
133
- end
134
- raise BadManifest.new("publish: must be a list of targets at '#{path}.publish'") unless block.is_a?(Array)
135
-
136
- block.each_with_index do |t, i|
137
- raise BadManifest.new("publish target ##{i} must be a mapping at '#{path}.publish'") unless t.is_a?(Hash)
138
-
139
- walk(t, %w[to tree template inject_boot], "#{path}.publish[#{i}]")
140
- end
141
- end
142
-
143
- def validate_rules!(rules)
144
- Array(rules).each_with_index do |r, i|
145
- path = "$.rules[#{i}]"
146
- reject_retired_rule_keys!(r, path)
147
- if r.is_a?(Hash) && r.key?("upkeep")
148
- raise BadManifest.new(
149
- "rule key `upkeep:` was removed (ADR 0093): move age-GC to `retention:` " \
150
- "and production (handler/template) to the entry's `source:`",
151
- )
152
- end
153
- walk(r, RULE_KEYS, path)
154
- FIELD_REGISTRY.each_value do |meta|
155
- next unless meta[:sub_keys]
14
+ # Root unknown-key check before Contract so it fires even when lanes: is empty.
15
+ Semantics.walk(raw, ROOT_KEYS, "$")
156
16
 
157
- value = r[meta[:yaml_key]]
158
- walk(value, meta[:sub_keys], "#{path}.#{meta[:yaml_key]}") if value.is_a?(Hash)
159
- end
160
- end
161
- end
162
-
163
- # ADR 0093 split production from age-GC: age-GC moved to the `retention:`
164
- # rule; intake cadence + production (handler/template) moved to the
165
- # entry's `source:` block. Legacy `lifecycle:`/`materialize:` rule keys
166
- # are rejected with a migration hint toward the new shape.
167
- def reject_retired_rule_keys!(rule, path)
168
- return unless rule.is_a?(Hash)
169
-
170
- hints = {
171
- "lifecycle" => "age GC moved to the `retention:` rule ({ ttl, action: drop|archive }); " \
172
- "intake cadence to the entry's `source: { ttl }`",
173
- "materialize" => "removed — materialization is automatic (a write enqueues a job; run `drain`)",
174
- }
175
- hints.each do |old, hint|
176
- next unless rule.key?(old)
177
-
178
- raise BadManifest.new("`#{old}:` was removed at '#{path}' (ADR 0093) — #{hint}.")
179
- end
180
- end
181
-
182
- def validate_roles!(roles)
183
- return if roles.nil?
184
- raise BadManifest.new("roles: must be a list") unless roles.is_a?(Array)
185
-
186
- roles.each_with_index do |r, i|
187
- path = "$.roles[#{i}]"
188
- walk(r, ROLE_KEYS, path)
189
- name = r["name"] or raise BadManifest.new("role at '#{path}' missing name")
190
- unless Textus::Role::NAMES.include?(name)
191
- raise BadManifest.new(
192
- "unknown role name '#{name}' at '#{path}' " \
193
- "(allowed: #{Textus::Role::NAMES.join(", ")})",
194
- )
195
- end
196
- Array(r["can"]).each do |verb|
197
- next if CAPABILITIES.include?(verb)
198
-
199
- # The quarantine capability folded into the converge capability (ADR 0090); a
200
- # manifest still naming the old quarantine capability (`ingest`, or
201
- # legacy `fetch`) gets a pointed hint rather than a bare error.
202
- hint = %w[ingest fetch].include?(verb) ? " — the quarantine capability folded into 'converge' (ADR 0090)" : ""
203
- raise BadManifest.new(
204
- "unknown capability '#{verb}' for role '#{name}' at '#{path}' " \
205
- "(known: #{CAPABILITIES.join(", ")})#{hint}",
206
- )
207
- end
208
- end
209
-
210
- author_holders = roles.count { |r| Array(r["can"]).include?("author") }
211
- return if author_holders <= 1
212
-
213
- raise BadManifest.new(
214
- "manifest declares #{author_holders} roles with the author capability; at most one is allowed",
215
- )
216
- end
217
-
218
- # Owners are validated against the SAME closed archetype set as role names
219
- # (ADR 0045 D1) so attribution can't bypass the closed-name guarantee.
220
- # Applies to both zone owners and entry owners; owner is optional, so a
221
- # nil owner is not an error.
222
- def validate_owners!(lanes, entries)
223
- Array(lanes).each_with_index do |z, i|
224
- check_owner!(z["owner"], "$.lanes[#{i}]")
225
- end
226
- Array(entries).each_with_index do |e, i|
227
- check_owner!(e["owner"], "$.entries[#{i}]")
228
- end
229
- end
17
+ result = Contract.call(raw)
18
+ raise BadManifest.new(format_first_error(result.errors.messages)) unless result.success?
230
19
 
231
- def check_owner!(owner, path)
232
- return if owner.nil?
233
- return if valid_owner?(owner)
234
-
235
- raise BadManifest.new(
236
- "invalid owner '#{owner}' at '#{path}' " \
237
- "(expected <archetype> or <archetype>:<subject>, " \
238
- "archetype one of: #{Textus::Role::NAMES.join(", ")})",
239
- )
240
- end
241
-
242
- # The owner-validation rule: an `owner:` token is either a bare archetype
243
- # (`agent`) or `<archetype>:<subject>` (`human:patrick`). The archetype is
244
- # gated against the closed Role::NAMES set (so attribution can't smuggle in
245
- # a name the role side rejects, ADR 0045 D1); the subject is the free-form
246
- # principal, validated by OWNER_SUBJECT_PATTERN. Split on the FIRST ':'
247
- # only — a subject may not itself contain ':' (the pattern excludes it), so
248
- # `human:a:b` is rejected.
249
- def valid_owner?(token)
250
- return false unless token.is_a?(String) && !token.empty?
251
-
252
- archetype, subject = token.split(":", 2)
253
- return false unless Textus::Role::NAMES.include?(archetype)
254
- return true if subject.nil?
255
-
256
- OWNER_SUBJECT_PATTERN.match?(subject)
257
- end
258
-
259
- def walk(hash, allowed, path)
260
- return unless hash.is_a?(Hash)
261
-
262
- hash.each_key do |k|
263
- next if allowed.include?(k)
264
-
265
- raise BadManifest.new("unknown key '#{k}' at '#{path}'")
266
- end
267
- end
268
-
269
- def validate_single_queue!(raw)
270
- queues = Array(raw["lanes"]).select { |z| z["kind"] == "queue" }.map { |z| z["name"] }
271
- return if queues.size <= 1
20
+ raise BadManifest.new("manifest must declare lanes:") if Array(raw["lanes"]).empty?
272
21
 
273
- raise BadManifest.new(
274
- "at most one lane may declare kind: queue (found: #{queues.join(", ")})",
275
- )
22
+ Semantics.check!(raw)
276
23
  end
277
24
 
278
- def validate_single_machine!(raw)
279
- machines = Array(raw["lanes"]).select { |z| z["kind"] == "machine" }.map { |z| z["name"] }
280
- return if machines.size <= 1
25
+ # Format the first dry-schema error to match the legacy path-prefixed style:
26
+ # "unknown key 'x' at '$.lanes[0]'" for extra-key errors;
27
+ # "manifest structure error at <path>: <msg>" for type/value errors.
28
+ def format_first_error(messages)
29
+ msg = messages.first
30
+ return "manifest structure error: unknown" unless msg
281
31
 
282
- raise BadManifest.new(
283
- "at most one lane may declare kind: machine (found: #{machines.join(", ")})",
284
- )
285
- end
32
+ parent = format_path(msg.path[0..-2])
33
+ key = msg.path.last
286
34
 
287
- # ADR 0093: retention (drop/archive) is age-based GC; it is invalid on a
288
- # derived entry (a derived entry regenerates from its source, it isn't aged
289
- # out). Per ADR 0095 the produce-method is read from source.from on the one
290
- # Produced kind, so there is no longer a kind to agree against the source.
291
- # (Replaces validate_upkeep_kinds!.)
292
- def validate_source_and_retention!(manifest)
293
- manifest.data.entries.each do |entry|
294
- retention = manifest.rules.for(entry.key).retention
295
- next if retention.nil?
296
- next unless entry.derived?
297
-
298
- raise BadManifest.new(
299
- "entry '#{entry.key}': a derived entry regenerates from its source; " \
300
- "retention (drop/archive) is invalid",
301
- )
35
+ if msg.text == "is not allowed"
36
+ "unknown key '#{key}' at '#{parent}'"
37
+ else
38
+ "manifest structure error at #{format_path(msg.path)}: #{msg.text}"
302
39
  end
303
40
  end
304
41
 
305
- # Write authority is derived from capabilities (ADR 0030): a lane of a
306
- # given kind can only be written by a role that holds the kind's required
307
- # verb. Reject a manifest declaring a lane whose required verb is held by
308
- # no role. Capabilities.resolve returns the defaults when `roles:` is nil,
309
- # so the capability union is all four verbs and every kind is satisfied.
310
- def validate_lane_kind_consistency!(raw)
311
- held = Capabilities.resolve(raw["roles"]).values.flatten.uniq
312
-
313
- Array(raw["lanes"]).each_with_index do |z, i|
314
- verb = KIND_REQUIRES_VERB[z["kind"]]
315
- next if verb.nil? || held.include?(verb)
316
-
317
- raise BadManifest.new(
318
- "lane '#{z["name"]}' (#{z["kind"]}) at '$.lanes[#{i}]' " \
319
- "needs a role with capability '#{verb}'; none declared",
320
- )
321
- end
42
+ def format_path(parts)
43
+ "$" + Array(parts).map { |p| p.is_a?(Integer) ? "[#{p}]" : ".#{p}" }.join
322
44
  end
323
45
  end
324
46
  end
@@ -13,6 +13,7 @@ module Textus
13
13
  "workspace" => "keep",
14
14
  "machine" => "converge",
15
15
  "queue" => "propose",
16
+ "raw" => "ingest",
16
17
  }.freeze
17
18
 
18
19
  LANE_KINDS = LANES.keys.freeze
@@ -23,11 +23,8 @@ module Textus
23
23
  RULE_KEYS = Keys::RULE_KEYS
24
24
  OWNER_SUBJECT_PATTERN = Keys::OWNER_SUBJECT_PATTERN
25
25
 
26
- # Public entry points — the validation walk lives in Schema::Validator
27
- # (ADR 0107). Kept here so callers keep speaking to `Schema`.
26
+ # Public entry point — the validation walk lives in Schema::Validator (ADR 0107).
28
27
  def self.validate!(raw) = Validator.validate!(raw)
29
-
30
- def self.validate_source_and_retention!(manifest) = Validator.validate_source_and_retention!(manifest)
31
28
  end
32
29
  end
33
30
  end
@@ -44,14 +44,12 @@ module Textus # rubocop:disable Style/OneClassPerFile
44
44
 
45
45
  def build(raw, root)
46
46
  data = Manifest::Data.parse(raw, root: root)
47
- manifest = new(
47
+ new(
48
48
  data: data,
49
49
  resolver: Manifest::Resolver.new(data),
50
50
  policy: data.policy,
51
51
  rules: Manifest::Rules.parse(raw["rules"] || []),
52
52
  )
53
- Manifest::Schema.validate_source_and_retention!(manifest) # ADR 0093
54
- manifest
55
53
  end
56
54
 
57
55
  def check_version!(raw, source)
@@ -3,7 +3,7 @@ require "json"
3
3
 
4
4
  module Textus
5
5
  module Ports
6
- class Queue
6
+ class JobStore
7
7
  # A unit of deferred work. Pure data. The id is `<type>:<digest>` where the
8
8
  # digest is over the args with sorted keys, so logically-identical enqueues
9
9
  # collide on the same id — which is how Queue dedups (file already exists).
@@ -10,7 +10,7 @@ module Textus
10
10
  # worker pool needs no central lock. Dedup falls out of the id-as-filename:
11
11
  # enqueueing an id that already exists is a no-op. ADR 0038 (runtime subtree),
12
12
  # ADR 0108 (instantiable port).
13
- class Queue
13
+ class JobStore
14
14
  STATES = %i[ready leased done failed].freeze
15
15
 
16
16
  def initialize(root:)
@@ -20,7 +20,7 @@ module Textus
20
20
 
21
21
  def enqueue(job)
22
22
  dest = path(:ready, job.id)
23
- return if File.exist?(dest) # dedup: identical work already queued
23
+ return if File.exist?(dest)
24
24
 
25
25
  write_atomic(dest, job.to_h)
26
26
  end
@@ -29,7 +29,6 @@ module Textus
29
29
  Dir.children(Textus::Layout.queue_state(@root, :ready)).map { |f| File.basename(f, ".json") }
30
30
  end
31
31
 
32
- # A claimed job plus the path it lives at, so ack/fail act on this copy.
33
32
  Leased = Struct.new(:job, :leased_path, keyword_init: true)
34
33
 
35
34
  def lease(worker_id:, lease_ttl:)
@@ -38,9 +37,9 @@ module Textus
38
37
  src = File.join(ready_dir, name)
39
38
  dst = File.join(Textus::Layout.queue_state(@root, :leased), name)
40
39
  begin
41
- File.rename(src, dst) # atomic claim; loser's rename raises ENOENT
40
+ File.rename(src, dst)
42
41
  rescue Errno::ENOENT
43
- next # another worker won this one
42
+ next
44
43
  end
45
44
  job = Job.from_h(JSON.parse(File.read(dst)))
46
45
  stamp_lease(dst, worker_id: worker_id, expires_at: Time.now.utc + lease_ttl)
@@ -54,9 +53,6 @@ module Textus
54
53
  File.rename(leased.leased_path, dest)
55
54
  end
56
55
 
57
- # Increment attempts and either requeue (transient) or dead-letter (attempts
58
- # exhausted). Returns :requeued or :dead_lettered so the worker can count
59
- # terminal failures distinctly from retries.
60
56
  def fail(leased, error:)
61
57
  job = leased.job
62
58
  job.attempts += 1
@@ -67,9 +63,6 @@ module Textus
67
63
  dead ? :dead_lettered : :requeued
68
64
  end
69
65
 
70
- # Return expired leases to ready/ (the holding worker crashed). Returns the
71
- # count reclaimed. At-least-once delivery: a job whose handler actually
72
- # finished but whose ack was lost will re-run — handlers must be idempotent.
73
66
  def reclaim(now:)
74
67
  leased_dir = Textus::Layout.queue_state(@root, :leased)
75
68
  count = 0
@@ -85,7 +78,7 @@ module Textus
85
78
  File.rename(src, dst)
86
79
  count += 1
87
80
  rescue Errno::ENOENT
88
- next # raced with another reclaimer / the worker's ack
81
+ next
89
82
  end
90
83
  count
91
84
  end
@@ -123,7 +116,7 @@ module Textus
123
116
  def write_atomic(dest, hash)
124
117
  tmp = "#{dest}.#{Process.pid}.tmp"
125
118
  File.write(tmp, JSON.pretty_generate(hash))
126
- File.rename(tmp, dest) # atomic on same filesystem
119
+ File.rename(tmp, dest)
127
120
  end
128
121
  end
129
122
  end
@@ -0,0 +1,50 @@
1
+ module Textus
2
+ module Produce
3
+ class Engine
4
+ def self.converge(container:, call:, keys:)
5
+ new(container:, call:).run(keys)
6
+ end
7
+
8
+ def initialize(container:, call:)
9
+ @container = container
10
+ @call = call
11
+ end
12
+
13
+ def run(keys)
14
+ results = { completed: [], failed: [] }
15
+ Array(keys).each { |key| produce_one(key, results) }
16
+ results
17
+ end
18
+
19
+ alias call run
20
+
21
+ private
22
+
23
+ def produce_one(key, results)
24
+ workflow = @container.workflows.for(key)
25
+ if workflow
26
+ Workflow::Runner.new(workflow, container: @container, call: @call).run(key)
27
+ else
28
+ publish_only(key)
29
+ end
30
+ results[:completed] << key
31
+ rescue StandardError => e
32
+ results[:failed] << { key: key, error: e.message }
33
+ end
34
+
35
+ def publish_only(key)
36
+ entry = @container.manifest.resolver.resolve(key).entry
37
+ return unless entry.publish_tree || !Array(entry.publish_to).empty?
38
+
39
+ reader = Textus::Envelope::Reader.from(container: @container)
40
+ entry_path = @container.manifest.resolver.resolve(key).path
41
+ return unless entry.publish_tree || File.exist?(entry_path)
42
+
43
+ pctx = Textus::Manifest::Entry::Base::PublishContext.new(
44
+ container: @container, call: @call, reader: reader.method(:read),
45
+ )
46
+ entry.publish_via(pctx)
47
+ end
48
+ end
49
+ end
50
+ end
@@ -0,0 +1,20 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "erb"
4
+
5
+ module Textus
6
+ module Produce
7
+ class Render
8
+ def initialize(template_loader:)
9
+ @template_loader = template_loader
10
+ end
11
+
12
+ def bytes_for(target:, data:, boot:)
13
+ raise ArgumentError.new("Produce::Render called for a verbatim target #{target.to.inspect}") unless target.renders?
14
+
15
+ ctx = target.inject_boot ? data.merge("boot" => boot) : data
16
+ ERB.new(@template_loader.call(target.template), trim_mode: "-").result_with_hash(ctx)
17
+ end
18
+ end
19
+ end
20
+ end
@@ -1,18 +1,26 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "dry-struct"
4
+
1
5
  module Textus
2
6
  # The agent session: per-connection (MCP), per-process (CLI), or per-loop
3
7
  # (Ruby) orientation state — the audit cursor plus the contract etag and
4
- # propose_lane captured at boot. Immutable Data value; advance_cursor
5
- # returns a new instance. ADR 0036; contract_etag widened in ADR 0074.
6
- Session = Data.define(:role, :cursor, :propose_lane, :contract_etag) do
7
- # Back-compat reader while lane terminology migrates.
8
- def propose_zone = propose_lane
8
+ # propose_lane captured at boot. Immutable Dry::Struct::Value; advance_cursor
9
+ # and with return new instances. ADR 0036; contract_etag widened in ADR 0074.
10
+ class Session < Dry::Struct
11
+ attribute :role, Types::RoleName
12
+ attribute :cursor, Types::Cursor
13
+ attribute :propose_lane, Types::String.optional
14
+ attribute :contract_etag, Types::String
15
+
16
+ def with(**attrs) = self.class.new(to_h.merge(attrs))
9
17
 
10
18
  def advance_cursor(new_cursor) = with(cursor: new_cursor)
11
19
 
12
20
  def check_etag!(observed_etag)
13
21
  return if observed_etag == contract_etag
14
22
 
15
- raise Textus::Surfaces::MCP::ContractDrift.new(
23
+ raise Textus::ContractDrift.new(
16
24
  "contract changed (manifest/hooks/schemas were #{short_etag(contract_etag)}, " \
17
25
  "now #{short_etag(observed_etag)}); re-run boot",
18
26
  )
@@ -21,8 +29,7 @@ module Textus
21
29
  private
22
30
 
23
31
  # First 8 hex chars after the "sha256:" prefix — a stable short id for
24
- # the drift diagnostic. Tolerates non-prefixed values (delete_prefix is
25
- # a no-op when the prefix is absent).
32
+ # the drift diagnostic.
26
33
  def short_etag(etag) = etag.to_s.delete_prefix("sha256:")[0, 8]
27
34
  end
28
35
  end
data/lib/textus/store.rb CHANGED
@@ -5,9 +5,9 @@ module Textus
5
5
  attr_reader :container
6
6
 
7
7
  # Readers are derived from the Container's schema, so the field set lives
8
- # in exactly one place (Container's Data.define). A new capability added
9
- # there is automatically exposed on the Store.
10
- Textus::Container.members.each do |field|
8
+ # in exactly one place (Container). A new capability added there is
9
+ # automatically exposed on the Store.
10
+ Textus::Container.attribute_names.each do |field|
11
11
  define_method(field) { @container.public_send(field) }
12
12
  end
13
13
 
@@ -44,16 +44,13 @@ module Textus
44
44
 
45
45
  def initialize(root)
46
46
  @container = build_container(File.expand_path(root))
47
- bootstrap_hooks
48
- steps.publish(:store_loaded, ctx: Step::Context.for(container: @container,
49
- call: Textus::Call.build(role: Role::DEFAULT)))
50
47
  end
51
48
 
52
49
  # Build an agent Session oriented at the current cursor/manifest — the
53
50
  # Ruby equivalent of an MCP `initialize`. ADR 0036.
54
51
  def session(role:)
55
52
  Textus::Session.new(
56
- role: role,
53
+ role: role.to_s,
57
54
  cursor: audit_log.latest_seq,
58
55
  propose_lane: manifest.policy.propose_lane_for(role),
59
56
  contract_etag: Textus::Etag.for_contract(root),
@@ -82,7 +79,7 @@ module Textus
82
79
  max_size: manifest.data.audit_config[:max_size],
83
80
  keep: manifest.data.audit_config[:keep],
84
81
  ),
85
- steps: Textus::Step::RegistryStore.new,
82
+ workflows: Workflow::Loader.load_all(root),
86
83
  gate: nil,
87
84
  )
88
85
  gate = Textus::Gate.new(container)
@@ -90,11 +87,5 @@ module Textus
90
87
  gate.instance_variable_set(:@container, container)
91
88
  container
92
89
  end
93
-
94
- def bootstrap_hooks
95
- Ports::AuditSubscriber.new(audit_log).attach(steps)
96
- Textus::Step::Builtin.register_all(steps)
97
- Textus::Step::Loader.new(registry: steps).load_dir(File.join(root, "steps"))
98
- end
99
90
  end
100
91
  end