hecks 1.4.0 → 1.5.0

data/lib/hecks/forms/port_argument.rb

@@ -22,6 +22,13 @@ module Hecks
     module PortArgument
       module_function
 
+      # Reads the `-p`/`--port` argument out of an argv array.
+      #
+      # @param argv [Array<String>] the command-line arguments, ARGV-shaped
+      # @param default [Integer] the port to use when neither spelling appears at all
+      # @return [Array(Integer, nil), Array(nil, String)] `[port, nil]` on a clean
+      #   parse, or `[nil, message]` when an explicit port was given but isn't a
+      #   real port number
       def parse(argv, default: 4567)
         equals = argv.find { |arg| arg.start_with?("--port=") }
         return resolve(equals.split("=", 2).last) if equals
@@ -32,6 +39,11 @@ module Hecks
         resolve(argv[index + 1])
       end
 
+      # Validates and converts a raw `-p`/`--port` argument value.
+      #
+      # @param value [String, nil] the text following `-p`/`--port`, or nil if none
+      # @return [Array(Integer, nil), Array(nil, String)] `[port, nil]` if `value`
+      #   is a whole number between 1 and 65535, or `[nil, message]` otherwise
       def resolve(value)
         return [nil, "-p/--port requires a value"] if value.nil? || value.empty?
         return [nil, "-p/--port must be a whole number, got #{value.inspect}"] unless value.match?(/\A\d+\z/)

data/lib/hecks/forms/query_form_renderer.rb

@@ -20,6 +20,21 @@ module Hecks
     # exactly the same kind of link on submit; and the results table once
     # a request actually supplies parameters.
     module QueryFormRenderer
+      # Renders one query's whole GET view: header, canonical link, quick links, filter
+      # form, any error, results, and the inspect panel.
+      #
+      # @param registry [Runtime::Registry] the booted registry, for resolving reference
+      #   fields' target aggregates
+      # @param domain [String] the owning chapter's name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the query belongs to
+      # @param query [Bluebook::Query] the query being rendered
+      # @param action [String] the form's `action` URL and the canonical link's base
+      # @param params [Hash] the request's own query params, pre-filling the filter form
+      # @param results [Array<Hash>, nil] the query's own answer rows; `nil` renders no
+      #   results section
+      # @param error [StandardError, nil] a raised error to show in the error banner;
+      #   `nil` renders none
+      # @return [String] the page body markup
       def self.render(registry:, domain:, aggregate:, query:, action:, params: {}, results: nil, error: nil)
         fields = query.attributes.map { |a| FieldShape.resolve(a, aggregate: aggregate) }
         reference_options = ReferenceOptions.collect(registry, domain, fields)
@@ -35,6 +50,12 @@ module Hecks
         HTML
       end
 
+      # Renders the query's title, description and badges.
+      #
+      # @param domain [String] the owning chapter's name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the query belongs to
+      # @param query [Bluebook::Query] the query being rendered
+      # @return [String] the header markup
       def self.header(domain, aggregate, query)
         <<~HTML
           <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}")}</h1>
@@ -43,12 +64,22 @@ module Hecks
         HTML
       end
 
+      # Renders the query's declared badges — today, just its `limit` when it declares one.
+      #
+      # @param query [Bluebook::Query] the query being rendered
+      # @return [String] the badge markup; `""` when the query declares no `limit`
       def self.badges(query)
         parts = []
         parts << %(<span class="badge">limit #{Escape.html(query.limit.to_h[:value])}</span>) if query.limit
         parts.join
       end
 
+      # Renders the query's plain-GET canonical link template, one `path={path}` per
+      # parameter.
+      #
+      # @param action [String] the query's base URL
+      # @param fields [Array<Forms::Field>] the resolved field tree naming the parameters
+      # @return [String] the help text and the templated link markup
       def self.canonical_link(action, fields)
         paths = Params.paths(fields)
         template = paths.empty? ? action : "#{action}?#{paths.map { |path| "#{path}={#{path}}" }.join('&')}"
@@ -64,6 +95,12 @@ module Hecks
       # would mean a cross product of links, which reads as noise rather
       # than help. A query with more than one is still fully reachable
       # through the filter form below.
+      #
+      # @param action [String] the query's base URL
+      # @param fields [Array<Forms::Field>] the resolved field tree to search for a
+      #   `:select` or `:radio` field
+      # @return [String] one clickable link per option of the first closed-set field
+      #   found; `""` when no field is `:select` or `:radio`
       def self.quick_links(action, fields)
         field = fields.find { |f| %i[select radio].include?(f.kind) }
         return "" unless field
@@ -75,6 +112,14 @@ module Hecks
         %(<div class="example-links">#{links.join}</div>)
       end
 
+      # Renders the GET filter form covering every declared parameter.
+      #
+      # @param action [String] the form's `action` URL
+      # @param fields [Array<Forms::Field>] the resolved field tree to render
+      # @param params [Hash] the request's own query params, pre-filling each field
+      # @param reference_options [Hash{String => Array<Array(String, String)>, nil}] each
+      #   `:reference` field's own dropdown options, as `ReferenceOptions.collect` returns
+      # @return [String] the form markup; `""` when the query declares no parameters
       def self.filter_form(action, fields, params, reference_options)
         return "" if fields.empty?
 
@@ -86,6 +131,10 @@ module Hecks
         HTML
       end
 
+      # Renders a raised error as a dismissable-looking alert banner.
+      #
+      # @param error [StandardError, nil] the error to show
+      # @return [String] the banner markup; `""` when `error` is `nil`
       def self.error_banner(error)
         return "" unless error
 
@@ -93,12 +142,26 @@ module Hecks
           "#{Escape.html(error.message)}</p></div>"
       end
 
+      # Renders the results heading and table, once a request actually supplied
+      # parameters.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose fields shape the table
+      # @param results [Array<Hash>, nil] the query's own answer rows
+      # @param domain [String] the owning chapter's name, for building record links
+      # @return [String] the results section markup; `""` when `results` is `nil`
       def self.results_section(aggregate, results, domain)
         return "" unless results
 
         "<h2>Results (#{results.size})</h2>#{RecordTable.render(aggregate, results, domain: domain)}"
       end
 
+      # Renders a collapsed panel with the query's own parameter list and raw IR JSON.
+      #
+      # @param domain [String] the owning chapter's name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the query belongs to
+      # @param query [Bluebook::Query] the query being rendered
+      # @param fields [Array<Forms::Field>] the resolved field tree, for the parameter list
+      # @return [String] the `<details>` panel markup
       def self.inspect_panel(domain, aggregate, query, fields)
         verb = "#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}"
         paths = Params.paths(fields)

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(", ")
@@ -72,6 +101,14 @@ module Hecks
       # 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?
@@ -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

@@ -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

@@ -18,6 +18,8 @@ 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
@@ -27,6 +29,10 @@ module Hecks
       # [[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/fqn.rb

@@ -8,10 +8,35 @@ 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
@@ -22,6 +47,13 @@ module Hecks
     # 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/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": [