Module: Textus::Manifest::Schema

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

Constant Summary collapse

ROOT_KEYS = 
%w[version roles zones entries rules audit].freeze
ROLE_KEYS = 
%w[name can].freeze
ZONE_KEYS = 
%w[name kind owner desc].freeze
LANES =

The closed coordination vocabulary (ADR 0028; completed at five in ADR 0033; unified here in ADR 0034). Each lane pairs a zone-kind with the single capability that authorizes originating bytes in it — a total bijection. This table is the ONE source of truth; the three legacy constants below are derived from it so a zone-kind and its required capability cannot drift. Key order is canon-first so the unknown-kind error message reads canon, workspace, quarantine, queue, derived.

{
  "canon" => "author",
  "workspace" => "keep",
  "quarantine" => "fetch",
  "queue" => "propose",
  "derived" => "build",
}.freeze
ZONE_KINDS = 
LANES.keys.freeze
CAPABILITIES = 
LANES.values.freeze
KIND_REQUIRES_VERB = 
LANES
ENTRY_KEYS = 
%w[
  key path zone kind schema owner nested format
  compute template publish
  intake events inject_boot ignore tracked
].freeze
PUBLISH_KEYS =

ADR 0052: the typed publish block — ‘publish: { to: […] }` (file fan-out) xor `publish: { tree: “dir” }` (subtree mirror).

%w[to tree].freeze
COMPUTE_KEYS = 
%w[kind select pluck sort_by limit transform command sources].freeze
INTAKE_KEYS = 
%w[handler config].freeze
RULE_KEYS = 
%w[match intake_handler_allowlist guard lifecycle].freeze
LIFECYCLE_KEYS = 
%w[ttl on_expire budget_ms].freeze
AUDIT_KEYS = 
%w[max_size keep].freeze
OWNER_SUBJECT_PATTERN =

Syntactic shape of an ‘owner:` subject token (the `patrick` in `human:patrick`) — the subject half of the owner-validation rule below. Role supplies the archetype set (Role::NAMES); this pattern is the owner-specific part, so it lives with the rule that composes them (ADR 0045 D1). Acting-role names are gated by Role::NAMES, not a regex.

/\A[a-z][a-z0-9_-]*\z/

Class Method Summary collapse

Class Method Details

.check_owner!(owner, path) ⇒ Object

Raises:



186
187
188
189
190
191
192
193
194
195
 
# File 'lib/textus/manifest/schema.rb', line 186

def self.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:



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/textus/manifest/schema.rb', line 90

def self.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

.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) 


204
205
206
207
208
209
210
211
212
 
# File 'lib/textus/manifest/schema.rb', line 204

def self.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:



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

def self.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_zone_kind_consistency!(raw)
end

.validate_entries!(entries) ⇒ Object 



74
75
76
77
78
79
80
81
82
83
 
# File 'lib/textus/manifest/schema.rb', line 74

def self.validate_entries!(entries)
  Array(entries).each_with_index do |e, i|
    path = "$.entries[#{i}]"
    reject_retired_publish_keys!(e, path)
    walk(e, ENTRY_KEYS, path)
    validate_publish_block!(e, path)
    walk(e["compute"], COMPUTE_KEYS, "#{path}.compute") if e["compute"].is_a?(Hash)
    walk(e["intake"], INTAKE_KEYS, "#{path}.intake") if e["intake"].is_a?(Hash)
  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.



177
178
179
180
181
182
183
184
 
# File 'lib/textus/manifest/schema.rb', line 177

def self.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

Shape of the ADR 0052 publish block: a Hash whose only keys are to/tree. Exclusivity (both set) and per-mode rules stay in Publish.resolve (ADR 0049).

Raises:



124
125
126
127
128
129
130
131
 
# File 'lib/textus/manifest/schema.rb', line 124

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

  block = entry["publish"]
  raise BadManifest.new("publish: must be a mapping with `to:` or `tree:` at '#{path}.publish'") unless block.is_a?(Hash)

  walk(block, PUBLISH_KEYS, "#{path}.publish")
end

.validate_roles!(roles) ⇒ Object

Raises:



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/textus/manifest/schema.rb', line 141

def self.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)

      raise BadManifest.new(
        "unknown capability '#{verb}' for role '#{name}' at '#{path}' " \
        "(known: #{CAPABILITIES.join(", ")})",
      )
    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 



133
134
135
136
137
138
139
 
# File 'lib/textus/manifest/schema.rb', line 133

def self.validate_rules!(rules)
  Array(rules).each_with_index do |r, i|
    path = "$.rules[#{i}]"
    walk(r, RULE_KEYS, path)
    walk(r["lifecycle"], LIFECYCLE_KEYS, "#{path}.lifecycle") if r["lifecycle"].is_a?(Hash)
  end
end

.validate_single_queue!(raw) ⇒ Object

Raises:



224
225
226
227
228
229
230
231
 
# File 'lib/textus/manifest/schema.rb', line 224

def self.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_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.



238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/textus/manifest/schema.rb', line 238

def self.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 



60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/textus/manifest/schema.rb', line 60

def self.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"])

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

.walk(hash, allowed, path) ⇒ Object 



214
215
216
217
218
219
220
221
222
 
# File 'lib/textus/manifest/schema.rb', line 214

def self.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