hecks 1.3.0 → 1.5.0

data/lib/hecks/forms/record_renderer.rb

@@ -11,6 +11,12 @@ module Hecks
     # do (facade/surface/aggregate_door.rb) — so they exist for every
     # aggregate whether or not its bluebook declared a query at all.
     module RecordRenderer
+      # Renders the index page listing every record of one aggregate.
+      #
+      # @param registry [Runtime::Registry] the booted registry holding the domain
+      # @param domain [String, Symbol] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose records are listed
+      # @return [String] the index page's rendered HTML
       def self.index(registry:, domain:, aggregate:)
         instances = registry.repository(domain, aggregate).all
         <<~HTML
@@ -23,6 +29,12 @@ module Hecks
         HTML
       end
 
+      # Renders the "+ Command" buttons for every creating command.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose creating commands
+      #   are linked
+      # @return [String] HTML action buttons, or `""` if the aggregate declares none
       def self.creating_links(domain, aggregate)
         creators = aggregate.commands.select(&:creates?)
         return "" if creators.empty?
@@ -34,6 +46,15 @@ module Hecks
         %(<div class="actions">#{links.join}</div>)
       end
 
+      # Renders one record's state page: its current fields, plus the commands and
+      # queries it can dispatch next.
+      #
+      # @param registry [Runtime::Registry] the booted registry holding the domain
+      # @param domain [String, Symbol] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
+      # @param id [String, Object] the record's identity
+      # @return [String, nil] the record page's rendered HTML, or nil if no record
+      #   has that id
       def self.show(registry:, domain:, aggregate:, id:)
         instance = registry.repository(domain, aggregate).find(id)
         return nil unless instance
@@ -50,6 +71,10 @@ module Hecks
         HTML
       end
 
+      # Renders a record's state as an HTML field table.
+      #
+      # @param state [Hash{Symbol => Object}] the record's stored attribute values
+      # @return [String] an HTML table of the state's fields, values escaped
       def self.state_table(state)
         rows = state.map do |key, value|
           "<tr><th>#{Escape.html(Humanize.label(key.to_s))}</th><td>#{Escape.html(render_value(value))}</td></tr>"
@@ -60,6 +85,10 @@ module Hecks
       # `Value.materialize` first — a stored field is a `Runtime::Value`
       # wherever its attribute is a value object, not a plain Hash (see
       # record_table.rb's own note on the same read).
+      #
+      # @param value [Object] a stored field's value, possibly a `Runtime::Value`
+      # @return [String] the value rendered as text: a Hash as `"key: value, ..."`
+      #   pairs, an Array `;`-joined, anything else its own `to_s`
       def self.render_value(value)
         case (value = Runtime::Value.materialize(value))
         when Hash then value.map { |k, v| "#{k}: #{render_value(v)}" }.join(", ")
@@ -68,17 +97,25 @@ module Hecks
         end
       end
 
-      # Every non-creating command, EXCEPT a lifecycle transition that does
+      # Every non-creating command, except a lifecycle transition that does
       # not apply from the record's current state — the same rule
       # `Rules#admissible_transition` enforces at dispatch, read here so a
       # link that would only refuse is never offered in the first place.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
+      # @param id [String, Object] the record's identity
+      # @param current_state [String, nil] the record's current lifecycle state, or
+      #   nil if the aggregate has no lifecycle field or it is unset
+      # @return [String] an HTML list of admissible command links, or a message
+      #   when no command currently applies
       def self.command_links(domain, aggregate, id, current_state)
         commands = aggregate.commands.reject(&:creates?).select { |cmd| applies?(aggregate, cmd, current_state) }
         return "<p><em>No commands act on an existing #{Escape.html(aggregate.hecks_name)}.</em></p>" if commands.empty?
 
         items = commands.map do |cmd|
           # L12 — the id is free-form (S3): percent-encoded as the query
-          # VALUE (a raw `&` here would smuggle a second bogus query
+          # value (a raw `&` here would smuggle a second bogus query
           # parameter), then the assembled href is attribute-escaped as
           # usual.
           href = "/#{domain}/#{aggregate.hecks_name}/#{cmd.hecks_name}.html?to=#{Escape.url(id)}"
@@ -88,6 +125,14 @@ module Hecks
         %(<ul class="verb-list">#{items.join}</ul>)
       end
 
+      # Whether the aggregate's lifecycle admits dispatching `command` from
+      # `current_state`.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate the command belongs to
+      # @param command [Bluebook::Command] the command to check
+      # @param current_state [String, nil] the record's current lifecycle state
+      # @return [Boolean] true if the aggregate declares no lifecycle transitions for
+      #   this command, or one of them admits `current_state`
       def self.applies?(aggregate, command, current_state)
         transitions = aggregate.lifecycle&.transitions_for(command.hecks_name) || []
         return true if transitions.empty?
@@ -95,6 +140,12 @@ module Hecks
         transitions.any? { |t| t.from.nil? || Array(t.from).map(&:to_s).include?(current_state.to_s) }
       end
 
+      # Renders the "Queries" link list for an aggregate's own queries.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose queries are linked
+      # @return [String] an HTML section listing every query, or `""` if the
+      #   aggregate declares none
       def self.query_links(domain, aggregate)
         return "" if aggregate.queries.empty?
 
@@ -105,6 +156,13 @@ module Hecks
         %(<h2>Queries</h2><ul class="verb-list">#{items.join}</ul>)
       end
 
+      # Renders the full command-and-query index for an aggregate, independent of
+      # any one record's state.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose verbs are listed
+      # @return [String] an HTML section listing every non-creating command and every
+      #   query, or `""` if the aggregate declares neither
       def self.verb_list(domain, aggregate)
         commands = aggregate.commands.reject(&:creates?)
         return "" if commands.empty? && aggregate.queries.empty?

data/lib/hecks/forms/record_table.rb

@@ -5,7 +5,7 @@ module Hecks
   module Forms
     # The one shape every renderer in this directory reads a record as —
     # `id` plus its state hash. `Runtime::Instance` already answers both,
-    # so `repository.all`'s own records pass straight through; a QUERY's
+    # so `repository.all`'s own records pass straight through; a query's
     # answer does not (`QueryInterpreter#call` flattens `{id:}.merge(state)`
     # into one hash with no method to call — see
     # docs/command-form-and-query-form-bluebook.md's note on why), so
@@ -19,12 +19,26 @@ module Hecks
     # query's own results (query_form_renderer.rb) — the same records
     # read the same columns either way.
     module RecordTable
+      # Picks which fields to show as columns: identity, lifecycle state, then scalar
+      # attributes, capped at seven.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose records will be shown
+      # @return [Array<Symbol>] up to 7 unique field names, in that order; excludes
+      #   reference and list attributes
       def self.columns(aggregate)
         lifecycle = aggregate.lifecycle&.field
         scalars = aggregate.attributes.reject { |a| a.reference? || a.list? }.map(&:name)
         [*aggregate.identity_heads, lifecycle, *scalars].compact.uniq.first(7)
       end
 
+      # Renders a list of records as an HTML table, one row per record.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate the records belong to
+      # @param instances [Array<Runtime::Instance, Forms::Record>] the records to render;
+      #   anything answering `#id`/`#state` works
+      # @param domain [String] the owning chapter's name, for building each row's link
+      # @return [String] the table markup; `"<p><em>No records.</em></p>"` when
+      #   `instances` is empty
       def self.render(aggregate, instances, domain:)
         cols = columns(aggregate)
         head = (["id"] + cols).map { |name| "<th>#{Escape.html(Humanize.label(name.to_s))}</th>" }.join
@@ -39,6 +53,13 @@ module Hecks
         HTML
       end
 
+      # Renders one record's own table row, linked to its show page.
+      #
+      # @param instance [Runtime::Instance, Forms::Record] the record to render
+      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
+      # @param cols [Array<Symbol>] the column field names, as `columns` returns them
+      # @param domain [String] the owning chapter's name, for building the row's link
+      # @return [String] the `<tr>` markup
       def self.row(instance, aggregate, cols, domain)
         cells = cols.map { |name| "<td>#{Escape.html(cell(instance, name))}</td>" }.join
         # L12 — the id is free-form (S3): percent-encoded as the path
@@ -50,6 +71,12 @@ module Hecks
         "<tr><td><a href=\"#{Escape.attr(href)}\">#{Escape.html(instance.id)}</a></td>#{cells}</tr>"
       end
 
+      # Reads one field's value for display, unwrapped to a single cell value.
+      #
+      # @param instance [Runtime::Instance, Forms::Record] the record to read
+      # @param name [Symbol] the field name to read
+      # @return [Object] the field's own value; for a Hash-shaped value object, its
+      #   first member's value; `""` for `nil`
       def self.cell(instance, name)
         # `state` holds `Runtime::Value` wherever an attribute is a value
         # object, not a plain Hash — `.materialize` is the runtime's own

data/lib/hecks/forms/reference_options.rb

@@ -7,12 +7,27 @@ module Hecks
     # resolve against the same repository the same way, and neither word
     # owns this more than the other.
     module ReferenceOptions
+      # Collects every `:reference` field's own dropdown options out of a resolved field
+      # tree.
+      #
+      # @param registry [Runtime::Registry] the booted registry to read repositories from
+      # @param domain [String] the owning chapter's name
+      # @param fields [Array<Forms::Field>] the resolved field tree to search
+      # @return [Hash{String => Array<Array(String, String)>, nil}] one entry per
+      #   `:reference` field found, keyed by its `path`; `nil` when the field's target
+      #   could not be resolved or its options could not be read
       def self.collect(registry, domain, fields)
         targets = {}
         walk(fields) { |field| targets[field.path] = field.target_aggregate if field.kind == :reference }
         targets.transform_values { |aggregate| aggregate && options_for(registry, domain, aggregate) }
       end
 
+      # Visits every field in a tree, depth-first, including each `:list`/`:group`
+      # field's own children.
+      #
+      # @param fields [Array<Forms::Field>] the field tree to walk
+      # @yieldparam field [Forms::Field] each field visited, parent before children
+      # @return [void]
       def self.walk(fields, &block)
         fields.each do |field|
           block.call(field)
@@ -20,6 +35,15 @@ module Hecks
         end
       end
 
+      # Reads up to 200 records' ids as `<select>` options, for one reference field's
+      # target aggregate.
+      #
+      # @param registry [Runtime::Registry] the booted registry to read the repository from
+      # @param domain [String] the owning chapter's name
+      # @param aggregate [Bluebook::Aggregate] the referenced aggregate to list
+      # @return [Array<Array(String, String)>, nil] up to 200 `[id, id]` pairs; `nil` when
+      #   the repository cannot be resolved (a wiring gap degrades to a plain text id
+      #   input, not a 500)
       def self.options_for(registry, domain, aggregate)
         registry.repository(domain, aggregate).all.first(200).map { |instance| [instance.id, instance.id] }
       rescue StandardError

data/lib/hecks/forms/value_object_shape.rb

@@ -1,11 +1,11 @@
 module Hecks
   module Forms
-    # THE VALUE-OBJECT CLASSIFICATION every consumer of a resolved VO
+    # The value-object classification every consumer of a resolved VO
     # shape needs, spelled once — `field_shape.rb` (a command's own
     # form), `ui_schema.rb` (embryonaut_console's table/detail-panel
     # renderer, a separate app, not this repo), and
     # `adapters/driven/sql_query_builder.rb` (a query's own ORDER BY/
-    # WHERE compiler) each grew their own copy of "is this VO money-
+    # where compiler) each grew their own copy of "is this VO money-
     # shaped," "does it have exactly one attribute, worth unwrapping,"
     # and "which member of it is numeric" — the same three questions,
     # answered identically by definition (a VO's shape doesn't change
@@ -18,15 +18,21 @@ module Hecks
       # every money-shaped VO in the corpus spells it exactly this way,
       # the two-attribute convention the language itself never enforces
       # but every real chapter follows.
+      # @param value_object [Bluebook::ValueObject] the value object to classify
+      # @return [Boolean] true if its attributes are exactly `cents` and `currency`
       def money?(value_object)
         value_object.attributes.map { |a| a.name.to_s }.sort == %w[cents currency]
       end
 
-      # A VO with exactly one attribute is a NAME for a scalar, not a
+      # A VO with exactly one attribute is a name for a scalar, not a
       # genuine group (EmailAddress{address}, CustomerNumber{value}) —
       # [[feedback_name_the_scalar_field]]'s own reasoning, shared here
       # rather than re-decided per caller. Returns the sole attribute,
       # or nil for anything else.
+      #
+      # @param value_object [Bluebook::ValueObject] the value object to inspect
+      # @return [Bluebook::Attribute, nil] its one declared attribute, or nil if
+      #   it declares zero or more than one
       def sole_attribute(value_object)
         return nil unless value_object.attributes.size == 1
 
@@ -38,6 +44,10 @@ module Hecks
       # money-shaped (money's own two members are handled by `money?`
       # instead, since which one governs ordering is a money-specific
       # decision, not a general "pick the first number" one).
+      #
+      # @param value_object [Bluebook::ValueObject] the value object to inspect
+      # @return [Bluebook::Attribute, nil] its first Integer- or Float-typed
+      #   attribute, or nil if it declares none
       def numeric_member(value_object)
         value_object.attributes.find { |a| %w[Integer Float].include?(a.type.to_s) }
       end

data/lib/hecks/forms.rb

@@ -2,7 +2,7 @@
 # `query_form.bluebook` will eventually become — see docs/
 # command-form-and-query-form-bluebook.md), the IR->HTML renderers, and
 # the Rack app that content-negotiates between them and a plain JSON
-# reading of the same dispatch. NOT required by `require "hecks"`
+# reading of the same dispatch. Not required by `require "hecks"`
 # itself — a project that never boots this file never pays for `rack`,
 # the same lazy-dependency discipline the Gemfile's own comment already
 # holds `pg`/`oauth2`/`aws-sdk-lambda` to.
@@ -19,7 +19,7 @@ module Hecks
   # `expose` deliberately does and does not cover.
   module Forms
     # `expose`'s own declaration — "which chapters does this app expose" —
-    # kept OUTSIDE the `Hecks.*` collector convention (`Hecks.bluebook`,
+    # kept outside the `Hecks.*` collector convention (`Hecks.bluebook`,
     # `Hecks.hecksagon`, ...) and outside `Runtime::Registry` entirely, on
     # purpose: a real language word goes through `syntax.bluebook` and
     # `MetaValidator` (see docs/implemented/guides/extending-hecks.md, "a new word is a
@@ -30,29 +30,49 @@ module Hecks
     # see docs/command-form-and-query-form-bluebook.md, "why this isn't
     # syntax.bluebook yet".
     #
-    # ONE `expose` GRANTS A WHOLE CHAPTER, not a command or a query
+    # One `expose` grants a whole chapter, not a command or a query
     # individually — the future `command_form.bluebook`/`query_form.bluebook`
-    # words are PER-DECLARATION (one command, one query, its own form/view,
+    # words are per-declaration (one command, one query, its own form/view,
     # possibly its own overrides), which `expose` doesn't do today and was
     # never trying to; it's the coarse "turn this chapter's forms on at
     # all" switch those finer words will eventually sit inside.
     class Config
       attr_reader :name, :exposes
 
+      # @param name [String, Symbol] the app name this configuration is registered under;
+      #   stored as a String
       def initialize(name)
         @name    = name.to_s
         @exposes = []
       end
 
+      # Switches on the forms of one whole chapter for this app; called inside the
+      # `Forms.configure` block.
+      #
+      # @param chapter_name [String, Symbol] name of the chapter (domain) to expose, such as
+      #   `"Banking"`; stored as a String
+      # @return [Array<String>] every chapter name exposed so far, in declaration order
       def expose(chapter_name) = @exposes << chapter_name.to_s
     end
 
+    # Declares an app and the chapters it exposes, replacing any earlier configuration
+    # registered under the same name.
+    #
+    # @param name [String, Symbol] the app name `App.for` later looks the configuration up by
+    # @yield evaluated with `instance_eval` against the new `Forms::Config`, so a bare
+    #   `expose "Banking"` inside the block reaches `Config#expose`; optional
+    # @return [Forms::Config] the configuration just registered
     def self.configure(name, &block)
       config = Config.new(name)
       config.instance_eval(&block) if block
       (@configs ||= {})[config.name] = config
     end
 
+    # Looks up the configuration an earlier `Forms.configure` registered.
+    #
+    # @param name [String, Symbol] the app name given to `Forms.configure`
+    # @return [Forms::Config, nil] the app's configuration, or nil when no app of that name
+    #   has been configured
     def self.config(name) = (@configs || {})[name.to_s]
   end
 end

data/lib/hecks/fqn.rb

@@ -8,20 +8,52 @@ module Hecks
 
     attr_reader :realm, :domain, :version, :aggregate, :verb, :kind
 
+    # Builds the FQN of one command on an aggregate.
+    #
+    # @param realm [String, nil] deployment identity from the world, or nil for an
+    #   unrealmed address
+    # @param domain [String] the domain name
+    # @param aggregate [String] the aggregate name the command belongs to
+    # @param command [String] the command's PascalCase verb
+    # @param version [String, nil] the pinned domain version, or nil for the
+    #   world's configured latest alias
+    # @return [Fqn] the command address
+    # @raise [Fqn::Invalid] if any segment is empty or contains a separator, or if
+    #   `command` is not a valid PascalCase command name
     def self.command(realm:, domain:, aggregate:, command:, version: nil)
       new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: command, kind: :command)
     end
 
+    # Builds the FQN of one query, either on an aggregate or domain-level.
+    #
+    # @param realm [String, nil] deployment identity from the world, or nil for an
+    #   unrealmed address
+    # @param domain [String] the domain name
+    # @param query [String] the query's snake_case verb
+    # @param aggregate [String, nil] the aggregate the query belongs to, or nil for
+    #   a domain-level read model
+    # @param version [String, nil] the pinned domain version, or nil for the
+    #   world's configured latest alias
+    # @return [Fqn] the query address
+    # @raise [Fqn::Invalid] if any segment is empty or contains a separator, or if
+    #   `query` is not a valid snake_case query name
     def self.query(realm:, domain:, query:, aggregate: nil, version: nil)
       new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: query, kind: :query)
     end
 
-    # ONE ORDER-DEPENDENT PARSE PIPELINE: split -> shape-validate -> dispatch
+    # One order-dependent parse pipeline: split -> shape-validate -> dispatch
     # on segment count -> split domain/version -> classify kind -> cross-
     # field validate -> construct. Each step consumes locals (segments, verb,
     # kind) the step before it derived; splitting would mean threading all of
     # them back out as parameters/returns between new methods, for no
     # readability gain over reading the pipeline top to bottom once.
+    #
+    # @param text [String] a `Realm::Domain::Aggregate.verb` address, with domain
+    #   optionally `@version`-pinned and aggregate optional for a domain-level query
+    # @return [Fqn] the parsed address
+    # @raise [Fqn::Invalid] if `text` is not shaped like a FQN, its verb is neither
+    #   PascalCase nor snake_case, its domain version is malformed, or it names a
+    #   domain-level command
     # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def self.parse(text)
       head, separator, verb = text.to_s.rpartition(".")
@@ -53,9 +85,28 @@ module Hecks
       new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: verb, kind: kind)
     end
 
+    # Whether `name` is a valid command verb: PascalCase.
+    #
+    # @param name [String, Symbol, #to_s] the candidate verb
+    # @return [Boolean] true if `name` matches the PascalCase command shape
     def self.command_name?(name) = /\A[A-Z][A-Za-z0-9]*\z/.match?(name.to_s)
+
+    # Whether `name` is a valid query verb: snake_case.
+    #
+    # @param name [String, Symbol, #to_s] the candidate verb
+    # @return [Boolean] true if `name` matches the snake_case query shape
     def self.query_name?(name)   = /\A[a-z][a-z0-9_]*\z/.match?(name.to_s)
 
+    # @param realm [String, nil] deployment identity from the world, or nil for an
+    #   unrealmed address
+    # @param domain [String] the domain name
+    # @param aggregate [String, nil] the aggregate name, or nil for a domain-level query
+    # @param verb [String] the command or query verb
+    # @param kind [Symbol, String] `:command` or `:query`
+    # @param version [String, nil] the pinned domain version, or nil for the
+    #   world's configured latest alias
+    # @raise [Fqn::Invalid] if any segment is empty or contains a separator, or if
+    #   `verb` does not match the shape required by `kind`
     def initialize(realm:, domain:, aggregate:, verb:, kind:, version: nil)
       @realm     = realm && segment(realm, "realm")
       @domain    = segment(domain, "domain")
@@ -68,7 +119,14 @@ module Hecks
       raise Invalid, "#{@kind} FQN has an invalid verb #{@verb.inspect}" unless valid
     end
 
+    # Whether this address names a command.
+    #
+    # @return [Boolean] true if this address's kind is `:command`
     def command? = @kind == :command
+
+    # Whether this address names a query.
+    #
+    # @return [Boolean] true if this address's kind is `:query`
     def query?   = @kind == :query
 
     def to_s

data/lib/hecks/framework/bluebook/governance.bluebook

@@ -2,6 +2,15 @@ Hecks.bluebook "Governance" do
   vision "Organizational authority is explicit, reviewable, and historically explainable."
   supporting
 
+  # WHAT THIS CHAPTER ANSWERS FOR EVERY DOMAIN THAT ATTACHES IT. The role
+  # check at dispatch, boot's refusal of an ungoverned `role`, the
+  # authorization adapter and the fuzzer's grant steering all read these
+  # three verbs from here, rather than recognising "Governance" by name.
+  provides "authorization",
+           assignments: "RoleAssignment.AssignmentsForActor",
+           grant:       "RoleAssignment.Assign",
+           transitions: "RoleTransition.Allowed"
+
   aggregate "RoleAssignment" do
     description "One actor holding one role, over one scope, from one point in time — revoked by setting when it ended, never deleted."
 

data/lib/hecks/framework/bluebook/privacy.bluebook

@@ -0,0 +1,155 @@
+Hecks.bluebook "Privacy" do
+  vision "Which fields of a domain's own aggregates are sensitive is a fact about that domain, declared apart from it — the domain itself never spells out that one of its own attributes is PII or PHI."
+  supporting
+
+  # A DOMAIN ATTACHING THIS NEVER MARKS ITSELF — `Mark`'s `role
+  # "Deployment"` matches every other wiring-time command in this
+  # codebase (`Hecksagon::UsesFramework`, `Tenancy::Tenant.Register`):
+  # something outside the domain's own bluebook decides a field is
+  # sensitive, the same way persistence binds are a wiring decision
+  # and not baked into an aggregate's own declaration.
+  aggregate "Marking" do
+    description "One attribute of one domain's own aggregate, flagged sensitive — and the role required to read it unredacted."
+
+    attribute :domain,         MarkingDomain
+    attribute :attribute_path, AttributePath
+    attribute :category,       Category
+    attribute :readable_by,    RoleName
+
+    identified_by :domain, :attribute_path
+
+    value_object "MarkingDomain" do
+      attribute :value, String
+      invariant("a marking names the domain it applies to") { !value.to_s.empty? }
+    end
+
+    # DOTTED, same convention Forms' own `Field#path` and a query's
+    # cross-object `where` clause already use — `"attendee.medications"`,
+    # not a bare leaf name, so a marking can reach into a nested value
+    # object rather than only a top-level attribute.
+    value_object "AttributePath" do
+      attribute :value, String
+      invariant("a marking names an attribute path") { !value.to_s.empty? }
+    end
+
+    # OPEN-ENDED ON PURPOSE — "pii", "phi", whatever else a consuming
+    # domain finds itself needing, none of it enumerated here. This
+    # bluebook is the mechanism (mark, gate, redact); it does not also
+    # own the vocabulary of sensitivity categories that exist in the
+    # world.
+    value_object "Category" do
+      attribute :value, String
+      invariant("a marking is categorized") { !value.to_s.empty? }
+    end
+
+    value_object "RoleName" do
+      attribute :value, String
+      invariant("reading a marked field unredacted requires a named role") { !value.to_s.empty? }
+    end
+
+    command "Mark" do
+      role "Deployment"
+      goal "Flag one attribute of a domain's own aggregate as sensitive, gating who may read it unredacted"
+
+      attribute :domain,         MarkingDomain
+      attribute :attribute_path, AttributePath
+      attribute :category,       Category
+      attribute :readable_by,    RoleName
+
+      emits Marked
+    end
+
+    command "Unmark" do
+      role "Deployment"
+      goal "Remove a sensitivity flag from an attribute"
+
+      reference_to Marking
+
+      emits Unmarked
+    end
+
+    query "ForDomain" do
+      description "Every marking declared for one domain, read by whatever gates or redacts that domain's own records."
+      attribute :domain, MarkingDomain
+      where(domain: :domain)
+    end
+  end
+
+  # **Cryptoshredding** — a right-to-erasure request satisfied without
+  # rewriting or deleting a single event. `key_reference` is an opaque
+  # handle a caller obtains from `Ports::KeyVault.issue` before
+  # dispatching `Issue`, the same "nothing is minted inside a bluebook"
+  # convention `Identity::Register`'s own `identity_id` and
+  # `Delivery::Record`'s own `message_id` already hold to (the
+  # expression sublanguage cannot call a port at all). The key material
+  # itself never appears here or on any emitted event — only the fact
+  # that a reference exists, and the fact that it was destroyed.
+  aggregate "SubjectKey" do
+    description "One data subject's own encryption key, from the moment it exists to the moment it is destroyed."
+
+    attribute :domain,        KeyDomain
+    attribute :subject_id,    SubjectId
+    attribute :key_reference, KeyReference
+
+    identified_by :domain, :subject_id
+
+    value_object "KeyDomain" do
+      attribute :value, String
+      invariant("a key names the domain its subject belongs to") { !value.to_s.empty? }
+    end
+
+    value_object "SubjectId" do
+      attribute :value, String
+      invariant("a key names the subject it was issued for") { !value.to_s.empty? }
+    end
+
+    value_object "KeyReference" do
+      attribute :value, String
+      invariant("a key carries the vault's own opaque reference to it") { !value.to_s.empty? }
+    end
+
+    # `Shred`'s own guard against running twice — the same mechanism
+    # `Compliance::PrivacyReview`'s `Clear`/`Escalate` already use rather
+    # than an optional timestamp plus a hand-written `given`.
+    lifecycle :status, default: "active" do
+      transition "Shred" => "shredded", from: "active"
+    end
+
+    command "Issue" do
+      role "System"
+      goal "Record that a subject's data is now encrypted under a fresh, dedicated key"
+
+      attribute :domain,        KeyDomain
+      attribute :subject_id,    SubjectId
+      attribute :key_reference, KeyReference
+
+      sets :domain
+      sets :subject_id
+      sets :key_reference
+
+      emits SubjectKeyIssued
+    end
+
+    # **Records destruction, never performs it** — the actual
+    # `Ports::KeyVault.destroy` call happens in driving-side code before
+    # this is ever dispatched, the same boundary `send_issue.rb` draws
+    # around `Delivery::Record` for an already-sent email. This
+    # command's own job is to make an already-irreversible fact
+    # durable, not to cause it.
+    command "Shred" do
+      role "Privacy officer"
+      goal "Mark this subject's key destroyed, so its ciphertext is recorded as permanently unrecoverable"
+
+      reference_to SubjectKey
+
+      emits SubjectKeyShredded
+    end
+
+    query "ForSubject" do
+      description "One subject's key record, checked before any attempt to decrypt their sensitive fields."
+      attribute :domain,     KeyDomain
+      attribute :subject_id, SubjectId
+      where(domain: :domain, subject_id: :subject_id)
+    end
+  end
+end

data/lib/hecks/framework/oidc.json

@@ -30,6 +30,21 @@
       "scope": "compliance:box_surrender_review.open",
       "verb": "Compliance::BoxSurrenderReview.Open",
       "role": "System"
+    },
+    {
+      "scope": "compliance:privacy_review.clear",
+      "verb": "Compliance::PrivacyReview.Clear",
+      "role": "Compliance officer"
+    },
+    {
+      "scope": "compliance:privacy_review.escalate",
+      "verb": "Compliance::PrivacyReview.Escalate",
+      "role": "Compliance officer"
+    },
+    {
+      "scope": "compliance:privacy_review.open",
+      "verb": "Compliance::PrivacyReview.Open",
+      "role": "System"
     }
   ],
   "roles": [