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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +52 -0
- data/README.md +53 -73
- data/SPEC.md +2 -5
- data/docs/architecture/README.md +149 -159
- data/lib/textus/action/accept.rb +0 -9
- data/lib/textus/action/audit.rb +0 -2
- data/lib/textus/action/blame.rb +0 -2
- data/lib/textus/action/boot.rb +2 -11
- data/lib/textus/action/data_mv.rb +1 -3
- data/lib/textus/action/deps.rb +1 -15
- data/lib/textus/action/doctor.rb +0 -2
- data/lib/textus/action/drain.rb +4 -6
- data/lib/textus/action/enqueue.rb +3 -5
- data/lib/textus/action/get.rb +1 -3
- data/lib/textus/action/ingest.rb +135 -0
- data/lib/textus/action/jobs.rb +1 -3
- data/lib/textus/action/key_delete.rb +0 -10
- data/lib/textus/action/key_delete_prefix.rb +1 -3
- data/lib/textus/action/key_mv.rb +1 -15
- data/lib/textus/action/key_mv_prefix.rb +1 -3
- data/lib/textus/action/list.rb +0 -2
- data/lib/textus/action/propose.rb +0 -2
- data/lib/textus/action/published.rb +0 -2
- data/lib/textus/action/pulse.rb +7 -38
- data/lib/textus/action/put.rb +1 -12
- data/lib/textus/action/rdeps.rb +2 -12
- data/lib/textus/action/reject.rb +0 -12
- data/lib/textus/action/rule_explain.rb +0 -4
- data/lib/textus/action/rule_lint.rb +1 -3
- data/lib/textus/action/rule_list.rb +0 -4
- data/lib/textus/action/schema_envelope.rb +0 -2
- data/lib/textus/action/uid.rb +0 -2
- data/lib/textus/action/where.rb +0 -2
- data/lib/textus/action/write_verb.rb +4 -18
- data/lib/textus/boot.rb +40 -109
- data/lib/textus/command.rb +6 -1
- data/lib/textus/container.rb +21 -5
- data/lib/textus/core/freshness/evaluator.rb +18 -34
- data/lib/textus/core/freshness/verdict.rb +1 -1
- data/lib/textus/doctor/check/notebook_sources.rb +50 -0
- data/lib/textus/doctor/check/protocol_version.rb +6 -6
- data/lib/textus/doctor/check/raw_asset_paths.rb +50 -0
- data/lib/textus/doctor/check/stale_reviewed_stamp.rb +54 -0
- data/lib/textus/doctor/check.rb +0 -1
- data/lib/textus/doctor.rb +3 -42
- data/lib/textus/envelope/reader.rb +46 -0
- data/lib/textus/envelope/writer.rb +209 -0
- data/lib/textus/envelope.rb +19 -6
- data/lib/textus/errors.rb +9 -5
- data/lib/textus/{entry → format}/base.rb +1 -6
- data/lib/textus/{entry → format}/json.rb +1 -4
- data/lib/textus/{entry → format}/markdown.rb +2 -6
- data/lib/textus/{entry → format}/text.rb +2 -6
- data/lib/textus/{entry → format}/yaml.rb +1 -4
- data/lib/textus/{entry.rb → format.rb} +9 -10
- data/lib/textus/gate/auth.rb +58 -12
- data/lib/textus/gate.rb +2 -0
- data/lib/textus/init.rb +16 -79
- data/lib/textus/jobs/base.rb +23 -0
- data/lib/textus/jobs/materialize.rb +20 -0
- data/lib/textus/{background → jobs}/plan.rb +1 -1
- data/lib/textus/jobs/planner.rb +101 -0
- data/lib/textus/jobs/retention.rb +48 -0
- data/lib/textus/jobs/sweep.rb +27 -0
- data/lib/textus/{background → jobs}/worker.rb +2 -2
- data/lib/textus/jobs.rb +15 -0
- data/lib/textus/key/path.rb +1 -1
- data/lib/textus/manifest/entry/base.rb +4 -19
- data/lib/textus/manifest/entry/parser.rb +27 -10
- data/lib/textus/manifest/entry/produced.rb +13 -34
- data/lib/textus/manifest/entry/publish/to_paths.rb +4 -4
- data/lib/textus/manifest/entry/publish.rb +0 -12
- data/lib/textus/manifest/entry/validators/format_matrix.rb +1 -1
- data/lib/textus/manifest/entry/validators.rb +0 -1
- data/lib/textus/manifest/policy/source.rb +14 -62
- data/lib/textus/manifest/policy.rb +2 -5
- data/lib/textus/manifest/resolver.rb +2 -2
- data/lib/textus/manifest/schema/contract.rb +61 -0
- data/lib/textus/manifest/schema/keys.rb +6 -20
- data/lib/textus/manifest/schema/semantics.rb +232 -0
- data/lib/textus/manifest/schema/validator.rb +24 -302
- data/lib/textus/manifest/schema/vocabulary.rb +1 -0
- data/lib/textus/manifest/schema.rb +1 -4
- data/lib/textus/manifest.rb +1 -3
- data/lib/textus/ports/{queue → job_store}/job.rb +1 -1
- data/lib/textus/ports/{queue.rb → job_store.rb} +6 -13
- data/lib/textus/produce/engine.rb +50 -0
- data/lib/textus/produce/render.rb +20 -0
- data/lib/textus/session.rb +15 -8
- data/lib/textus/store.rb +5 -14
- data/lib/textus/surfaces/mcp/catalog.rb +23 -11
- data/lib/textus/surfaces/mcp/errors.rb +0 -9
- data/lib/textus/surfaces/mcp/server.rb +87 -110
- data/lib/textus/surfaces/role_scope.rb +0 -4
- data/lib/textus/surfaces/watcher.rb +3 -3
- data/lib/textus/types.rb +15 -0
- data/lib/textus/version.rb +2 -2
- data/lib/textus/workflow/collector.rb +27 -0
- data/lib/textus/workflow/context.rb +5 -0
- data/lib/textus/workflow/dsl.rb +44 -0
- data/lib/textus/workflow/loader.rb +17 -0
- data/lib/textus/workflow/pattern.rb +18 -0
- data/lib/textus/workflow/registry.rb +21 -0
- data/lib/textus/workflow/runner.rb +99 -0
- data/lib/textus/workflow.rb +28 -0
- data/lib/textus.rb +12 -1
- metadata +67 -66
- data/lib/textus/action/pulse/scanner.rb +0 -118
- data/lib/textus/background/job/base.rb +0 -27
- data/lib/textus/background/job/materialize.rb +0 -31
- data/lib/textus/background/job/refresh.rb +0 -22
- data/lib/textus/background/job/sweep.rb +0 -31
- data/lib/textus/background/job.rb +0 -19
- data/lib/textus/background/planner/plan.rb +0 -113
- data/lib/textus/background/retention/apply.rb +0 -50
- data/lib/textus/doctor/check/handler_permit.rb +0 -34
- data/lib/textus/doctor/check/hooks.rb +0 -25
- data/lib/textus/doctor/check/intake_registration.rb +0 -46
- data/lib/textus/envelope/io/reader.rb +0 -48
- data/lib/textus/envelope/io/writer.rb +0 -211
- data/lib/textus/events.rb +0 -21
- data/lib/textus/init/templates/machine_intake.rb +0 -49
- data/lib/textus/init/templates/orientation_reducer.rb +0 -21
- data/lib/textus/manifest/entry/validators/events.rb +0 -22
- data/lib/textus/manifest/policy/handler_permit.rb +0 -17
- data/lib/textus/pipeline/acquire/handler.rb +0 -29
- data/lib/textus/pipeline/acquire/intake.rb +0 -132
- data/lib/textus/pipeline/acquire/projection.rb +0 -129
- data/lib/textus/pipeline/acquire/serializer/json.rb +0 -31
- data/lib/textus/pipeline/acquire/serializer/text.rb +0 -16
- data/lib/textus/pipeline/acquire/serializer/yaml.rb +0 -31
- data/lib/textus/pipeline/acquire/serializer.rb +0 -17
- data/lib/textus/pipeline/engine.rb +0 -97
- data/lib/textus/pipeline/render.rb +0 -25
- data/lib/textus/ports/audit_subscriber.rb +0 -42
- data/lib/textus/projection.rb +0 -103
- data/lib/textus/step/base.rb +0 -35
- data/lib/textus/step/builtin/csv_fetch.rb +0 -19
- data/lib/textus/step/builtin/ical_events_fetch.rb +0 -30
- data/lib/textus/step/builtin/json_fetch.rb +0 -18
- data/lib/textus/step/builtin/markdown_links_fetch.rb +0 -20
- data/lib/textus/step/builtin/rss_fetch.rb +0 -26
- data/lib/textus/step/builtin.rb +0 -22
- data/lib/textus/step/catalog.rb +0 -37
- data/lib/textus/step/context.rb +0 -74
- data/lib/textus/step/discovery.rb +0 -24
- data/lib/textus/step/error_log.rb +0 -32
- data/lib/textus/step/event_bus.rb +0 -113
- data/lib/textus/step/fetch.rb +0 -13
- data/lib/textus/step/fire_report.rb +0 -23
- data/lib/textus/step/loader.rb +0 -108
- data/lib/textus/step/observe.rb +0 -31
- data/lib/textus/step/registry_store.rb +0 -66
- data/lib/textus/step/signature.rb +0 -31
- data/lib/textus/step/transform.rb +0 -12
- data/lib/textus/step/validate.rb +0 -11
- data/lib/textus/step.rb +0 -10
- data/lib/textus/surfaces/mcp/session.rb +0 -9
- 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
|
-
#
|
|
5
|
-
#
|
|
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
|
-
|
|
17
|
-
|
|
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
|
-
|
|
158
|
-
|
|
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
|
-
|
|
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
|
-
|
|
274
|
-
"at most one lane may declare kind: queue (found: #{queues.join(", ")})",
|
|
275
|
-
)
|
|
22
|
+
Semantics.check!(raw)
|
|
276
23
|
end
|
|
277
24
|
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
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
|
-
|
|
283
|
-
|
|
284
|
-
)
|
|
285
|
-
end
|
|
32
|
+
parent = format_path(msg.path[0..-2])
|
|
33
|
+
key = msg.path.last
|
|
286
34
|
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
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
|
-
|
|
306
|
-
|
|
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
|
|
@@ -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
|
|
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
|
data/lib/textus/manifest.rb
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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
|
|
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)
|
|
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)
|
|
40
|
+
File.rename(src, dst)
|
|
42
41
|
rescue Errno::ENOENT
|
|
43
|
-
next
|
|
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
|
|
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)
|
|
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
|
data/lib/textus/session.rb
CHANGED
|
@@ -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
|
|
5
|
-
#
|
|
6
|
-
Session
|
|
7
|
-
|
|
8
|
-
|
|
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::
|
|
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.
|
|
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
|
|
9
|
-
#
|
|
10
|
-
Textus::Container.
|
|
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
|
-
|
|
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
|