Module: Textus::Manifest::Schema::Validator

Defined in:
lib/textus/manifest/schema/validator.rb

Overview

The manifest validation walk. Extracted from Schema (ADR 0107); the schema data now lives in Schema::Vocabulary (coordination vocabulary, LANES + derived) and Schema::Keys (key whitelists / FIELD_REGISTRY), re-exported on Schema — while the validation logic lives here. Lexically nested under Schema, so bare constant references (ROOT_KEYS, LANES, FIELD_REGISTRY, …) resolve to Schema’s constants.

Class Method Summary collapse

Class Method Details

.check_owner!(owner, path) ⇒ Object

Raises:



229
230
231
232
233
234
235
236
237
238
 
# File 'lib/textus/manifest/schema/validator.rb', line 229

def check_owner!(owner, path)
  return if owner.nil?
  return if valid_owner?(owner)

  raise BadManifest.new(
    "invalid owner '#{owner}' at '#{path}' " \
    "(expected <archetype> or <archetype>:<subject>, " \
    "archetype one of: #{Textus::Role::NAMES.join(", ")})",
  )
end

.reject_retired_publish_keys!(entry, path) ⇒ Object

Retired keys are no longer allowed, so ‘walk` would reject them as merely “unknown”; intercept first with the migration path so a pre-0.43 manifest gets a useful error. `publish_each` was removed (ADR 0051); `publish_to`/ `publish_tree` were folded into the `publish:` block (ADR 0052); `index_filename` was removed (ADR 0053).

Raises:



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/textus/manifest/schema/validator.rb', line 65

def reject_retired_publish_keys!(entry, path)
  return unless entry.is_a?(Hash)

  if entry.key?("publish_each")
    raise BadManifest.new(
      "publish_each was removed in 0.42.0 (ADR 0051) at '#{path}' — " \
      "mirror the subtree with `publish: { tree: \"...\" }`.",
    )
  end

  if entry.key?("publish_to")
    raise BadManifest.new(
      "publish_to was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
      "use `publish: { to: [...] }`.",
    )
  end

  if entry.key?("publish_tree")
    raise BadManifest.new(
      "publish_tree was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
      "use `publish: { tree: \"...\" }`.",
    )
  end

  return unless entry.key?("index_filename")

  raise BadManifest.new(
    "index_filename was removed in 0.43.0 (ADR 0053) at '#{path}' — a nested entry now enumerates " \
    "each file as a key; to mirror a directory of files to a consumer path use `publish: { tree: \"...\" }`.",
  )
end

.reject_retired_render_keys!(entry, path) ⇒ Object

ADR 0094: rendering is a publish concern. An entry no longer declares a build-time template or render flags — they move onto publish targets. Provenance lives in the data’s ‘_meta`, not a flag.

Raises:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/textus/manifest/schema/validator.rb', line 100

def reject_retired_render_keys!(entry, path)
  return unless entry.is_a?(Hash)

  if entry.key?("template")
    raise BadManifest.new(
      "entry-level `template:` was removed at '#{path}' (ADR 0094): rendering is a " \
      "publish concern — `publish: [{ to:, template: }]`.",
    )
  end
  if entry.key?("inject_boot")
    raise BadManifest.new(
      "entry-level `inject_boot:` was removed at '#{path}' (ADR 0094): it is a render " \
      "flag — `publish: [{ to:, inject_boot: }]`.",
    )
  end
  return unless entry.key?("provenance")

  raise BadManifest.new("entry-level `provenance:` was removed at '#{path}' (ADR 0094): provenance lives in the data's `_meta`.")
end

.reject_retired_rule_keys!(rule, path) ⇒ Object

ADR 0093 split production from age-GC: age-GC moved to the ‘retention:` rule; intake cadence + production (handler/template) moved to the entry’s ‘source:` block. Legacy `lifecycle:`/`materialize:` rule keys are rejected with a migration hint toward the new shape.



165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/textus/manifest/schema/validator.rb', line 165

def reject_retired_rule_keys!(rule, path)
  return unless rule.is_a?(Hash)

  hints = {
    "lifecycle" => "age GC moved to the `retention:` rule ({ ttl, action: drop|archive }); " \
                   "intake cadence to the entry's `source: { ttl }`",
    "materialize" => "moved to the entry's `source: { on_write: sync|async }`",
  }
  hints.each do |old, hint|
    next unless rule.key?(old)

    raise BadManifest.new("`#{old}:` was removed at '#{path}' (ADR 0093) — #{hint}.")
  end
end

.valid_owner?(token) ⇒ Boolean

The owner-validation rule: an ‘owner:` token is either a bare archetype (`agent`) or `<archetype>:<subject>` (`human:patrick`). The archetype is gated against the closed Role::NAMES set (so attribution can’t smuggle in a name the role side rejects, ADR 0045 D1); the subject is the free-form principal, validated by OWNER_SUBJECT_PATTERN. Split on the FIRST ‘:’ only — a subject may not itself contain ‘:’ (the pattern excludes it), so ‘human:a:b` is rejected.

Returns:

  • (Boolean) 


247
248
249
250
251
252
253
254
255
 
# File 'lib/textus/manifest/schema/validator.rb', line 247

def valid_owner?(token)
  return false unless token.is_a?(String) && !token.empty?

  archetype, subject = token.split(":", 2)
  return false unless Textus::Role::NAMES.include?(archetype)
  return true if subject.nil?

  OWNER_SUBJECT_PATTERN.match?(subject)
end

.validate!(raw) ⇒ Object

Raises:



13
14
15
16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/textus/manifest/schema/validator.rb', line 13

def validate!(raw)
  raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)

  walk(raw, ROOT_KEYS, "$")
  validate_roles!(raw["roles"])
  validate_zones!(raw["zones"])
  validate_entries!(raw["entries"])
  validate_owners!(raw["zones"], raw["entries"])
  validate_rules!(raw["rules"])
  walk(raw["audit"], AUDIT_KEYS, "$.audit") if raw["audit"].is_a?(Hash)
  validate_single_queue!(raw)
  validate_single_machine!(raw)
  validate_zone_kind_consistency!(raw)
end

.validate_entries!(entries) ⇒ Object 



49
50
51
52
53
54
55
56
57
58
 
# File 'lib/textus/manifest/schema/validator.rb', line 49

def validate_entries!(entries)
  Array(entries).each_with_index do |e, i|
    path = "$.entries[#{i}]"
    reject_retired_publish_keys!(e, path)
    reject_retired_render_keys!(e, path)
    walk(e, ENTRY_KEYS, path)
    validate_publish_block!(e, path)
    walk(e["source"], SOURCE_KEYS, "#{path}.source") if e["source"]
  end
end

.validate_owners!(zones, entries) ⇒ Object

Owners are validated against the SAME closed archetype set as role names (ADR 0045 D1) so attribution can’t bypass the closed-name guarantee. Applies to both zone owners and entry owners; owner is optional, so a nil owner is not an error.



220
221
222
223
224
225
226
227
 
# File 'lib/textus/manifest/schema/validator.rb', line 220

def validate_owners!(zones, entries)
  Array(zones).each_with_index do |z, i|
    check_owner!(z["owner"], "$.zones[#{i}]")
  end
  Array(entries).each_with_index do |e, i|
    check_owner!(e["owner"], "$.entries[#{i}]")
  end
end

.validate_publish_block!(entry, path) ⇒ Object

ADR 0094: publish is a LIST of target objects. The old ‘{ to: […] }` / `{ tree: … }` map forms are retired (fold hint).

Raises:



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/textus/manifest/schema/validator.rb', line 122

def validate_publish_block!(entry, path)
  return unless entry.is_a?(Hash) && entry.key?("publish")

  block = entry["publish"]
  if block.is_a?(Hash)
    raise BadManifest.new(
      "publish: at '#{path}.publish' must be a list of targets " \
      "[{ to:, template:? } | { tree: }] (ADR 0094); the map form was retired.",
    )
  end
  raise BadManifest.new("publish: must be a list of targets at '#{path}.publish'") unless block.is_a?(Array)

  block.each_with_index do |t, i|
    raise BadManifest.new("publish target ##{i} must be a mapping at '#{path}.publish'") unless t.is_a?(Hash)

    walk(t, %w[to tree template inject_boot], "#{path}.publish[#{i}]")
  end
end

.validate_roles!(roles) ⇒ Object

Raises:



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/textus/manifest/schema/validator.rb', line 180

def validate_roles!(roles)
  return if roles.nil?
  raise BadManifest.new("roles: must be a list") unless roles.is_a?(Array)

  roles.each_with_index do |r, i|
    path = "$.roles[#{i}]"
    walk(r, ROLE_KEYS, path)
    name = r["name"] or raise BadManifest.new("role at '#{path}' missing name")
    unless Textus::Role::NAMES.include?(name)
      raise BadManifest.new(
        "unknown role name '#{name}' at '#{path}' " \
        "(allowed: #{Textus::Role::NAMES.join(", ")})",
      )
    end
    Array(r["can"]).each do |verb|
      next if CAPABILITIES.include?(verb)

      # The quarantine capability folded into reconcile (ADR 0090); a
      # manifest still naming the old quarantine capability (`ingest`, or
      # legacy `fetch`) gets a pointed hint rather than a bare error.
      hint = %w[ingest fetch].include?(verb) ? " — the quarantine capability folded into 'reconcile' (ADR 0090)" : ""
      raise BadManifest.new(
        "unknown capability '#{verb}' for role '#{name}' at '#{path}' " \
        "(known: #{CAPABILITIES.join(", ")})#{hint}",
      )
    end
  end

  author_holders = roles.count { |r| Array(r["can"]).include?("author") }
  return if author_holders <= 1

  raise BadManifest.new(
    "manifest declares #{author_holders} roles with the author capability; at most one is allowed",
  )
end

.validate_rules!(rules) ⇒ Object 



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/textus/manifest/schema/validator.rb', line 141

def validate_rules!(rules)
  Array(rules).each_with_index do |r, i|
    path = "$.rules[#{i}]"
    reject_retired_rule_keys!(r, path)
    if r.is_a?(Hash) && r.key?("upkeep")
      raise BadManifest.new(
        "rule key `upkeep:` was removed (ADR 0093): move age-GC to `retention:` " \
        "and production (handler/template) to the entry's `source:`",
      )
    end
    walk(r, RULE_KEYS, path)
    FIELD_REGISTRY.each_value do |meta|
      next unless meta[:sub_keys]

      value = r[meta[:yaml_key]]
      walk(value, meta[:sub_keys], "#{path}.#{meta[:yaml_key]}") if value.is_a?(Hash)
    end
  end
end

.validate_single_machine!(raw) ⇒ Object

Raises:



276
277
278
279
280
281
282
283
 
# File 'lib/textus/manifest/schema/validator.rb', line 276

def validate_single_machine!(raw)
  machines = Array(raw["zones"]).select { |z| z["kind"] == "machine" }.map { |z| z["name"] }
  return if machines.size <= 1

  raise BadManifest.new(
    "at most one zone may declare kind: machine (found: #{machines.join(", ")})",
  )
end

.validate_single_queue!(raw) ⇒ Object

Raises:



267
268
269
270
271
272
273
274
 
# File 'lib/textus/manifest/schema/validator.rb', line 267

def validate_single_queue!(raw)
  queues = Array(raw["zones"]).select { |z| z["kind"] == "queue" }.map { |z| z["name"] }
  return if queues.size <= 1

  raise BadManifest.new(
    "at most one zone may declare kind: queue (found: #{queues.join(", ")})",
  )
end

.validate_source_and_retention!(manifest) ⇒ Object

ADR 0093: retention (drop/archive) is age-based GC; it is invalid on a derived entry (a derived entry regenerates from its source, it isn’t aged out). Per ADR 0095 the produce-method is read from source.from on the one Produced kind, so there is no longer a kind to agree against the source. (Replaces validate_upkeep_kinds!.)



290
291
292
293
294
295
296
297
298
299
300
301
 
# File 'lib/textus/manifest/schema/validator.rb', line 290

def validate_source_and_retention!(manifest)
  manifest.data.entries.each do |entry|
    retention = manifest.rules.for(entry.key).retention
    next if retention.nil?
    next unless entry.derived?

    raise BadManifest.new(
      "entry '#{entry.key}': a derived entry regenerates from its source; " \
      "retention (drop/archive) is invalid",
    )
  end
end

.validate_zone_kind_consistency!(raw) ⇒ Object

Write authority is derived from capabilities (ADR 0030): a zone of a given kind can only be written by a role that holds the kind’s required verb. Reject a manifest declaring a zone whose required verb is held by no role. Capabilities.resolve returns the defaults when ‘roles:` is nil, so the capability union is all four verbs and every kind is satisfied.



308
309
310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/textus/manifest/schema/validator.rb', line 308

def validate_zone_kind_consistency!(raw)
  held = Capabilities.resolve(raw["roles"]).values.flatten.uniq

  Array(raw["zones"]).each_with_index do |z, i|
    verb = KIND_REQUIRES_VERB[z["kind"]]
    next if verb.nil? || held.include?(verb)

    raise BadManifest.new(
      "zone '#{z["name"]}' (#{z["kind"]}) at '$.zones[#{i}]' " \
      "needs a role with capability '#{verb}'; none declared",
    )
  end
end

.validate_zones!(zones) ⇒ Object 



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/textus/manifest/schema/validator.rb', line 28

def validate_zones!(zones)
  Array(zones).each_with_index do |z, i|
    walk(z, ZONE_KEYS, "$.zones[#{i}]")
    if z["kind"].nil?
      raise BadManifest.new("zone '#{z["name"]}' at '$.zones[#{i}]' must declare a kind (one of: #{ZONE_KINDS.join(", ")})")
    end
    next if ZONE_KINDS.include?(z["kind"])

    if %w[quarantine derived].include?(z["kind"])
      raise BadManifest.new(
        "zone kind '#{z["kind"]}' at '$.zones[#{i}]' was folded into 'machine' (ADR 0091) — " \
        "use `kind: machine`",
      )
    end

    raise BadManifest.new(
      "unknown zone kind '#{z["kind"]}' at '$.zones[#{i}]' (known: #{ZONE_KINDS.join(", ")})",
    )
  end
end

.walk(hash, allowed, path) ⇒ Object 



257
258
259
260
261
262
263
264
265
 
# File 'lib/textus/manifest/schema/validator.rb', line 257

def walk(hash, allowed, path)
  return unless hash.is_a?(Hash)

  hash.each_key do |k|
    next if allowed.include?(k)

    raise BadManifest.new("unknown key '#{k}' at '#{path}'")
  end
end