hecks 5.0.0 → 7.0.0

data/lib/hecks/framework/bluebook/console_settings.bluebook

@@ -7,7 +7,7 @@ Hecks.bluebook "ConsoleSettings" do
   # plus a `Hecks.hecksagon "ConsoleSettings" do ... end` persistence binding.
 
   # Named ConsoleSettings, not "Forms" — Hecks::Forms (lib/hecks/forms/) names a
-  # different thing, a raw form/query renderer straight off any IR. This chapter
+  # different thing, a raw form/query renderer straight off any IR. This bluebook
   # is a curated, hand-authored dashboard's own settings.
 
   # Scopes everything presentation.yml carries except a collection's own
@@ -69,10 +69,9 @@ Hecks.bluebook "ConsoleSettings" do
       goal "Color one state"
 
       reference_to StateStyle
-      attribute :tone, one_of("good", "warn", "danger", "muted", "accent")
+      attribute :tone, one_of("good", "warn", "danger", "muted", "accent"), sets: true
 
-      sets :tone
-      emits ToneSet
+      emits StateStyleToned
     end
 
     command "SetAttention" do
@@ -80,10 +79,9 @@ Hecks.bluebook "ConsoleSettings" do
       goal "Mark whether one state needs a person's attention"
 
       reference_to StateStyle
-      attribute :attention, Flag
+      attribute :attention, Flag, sets: true
 
-      sets :attention
-      emits AttentionSet
+      emits StateStyleFlagged
     end
 
     command "SetExtra" do
@@ -91,15 +89,14 @@ Hecks.bluebook "ConsoleSettings" do
       goal "Carry whatever per-state fields aren't individually modeled yet (label, note, ...)"
 
       reference_to StateStyle
-      attribute :extra_json, StateStyleExtra
+      attribute :extra_json, StateStyleExtra, sets: true
 
-      sets :extra_json
-      emits StateStyleExtraSet
+      emits StateStyleAnnotated
     end
   end
 
   aggregate "Collection" do
-    description "One app aggregate's own console presentation — nav label, curated columns, detail-panel fields (with an optional entity state_filter and a row_columns subset), identity-assignment strategy, field formats, preconditions, and which query lists it. Every list-shaped piece is rows on this root, never a nested list inside a value object — the same 'an open map is rows on a head' shape Wiring::Setting and Query::AskOption already use, and the same reason: no value object here can hold a map, and this sidesteps ever needing to find out whether one can hold a plain list either."
+    description "One app aggregate's own console presentation — how it is named in the nav, where it sits, which field stands in for a whole record, and which query lists it. Its columns, detail-panel fields, identity assignment, preconditions and field formats are each a consistency boundary of their own: CollectionLayout, CollectionIdentity and CollectionRules, keyed by the same `agg`."
 
     attribute :agg,                  SettingsText
 
@@ -110,19 +107,6 @@ Hecks.bluebook "ConsoleSettings" do
     attribute :nav_order,            SettingsNumber, optional: true
     attribute :primary_field,        SettingsText, optional: true
     attribute :list_query,           SettingsText, optional: true
-    attribute :identity_field,       SettingsText, optional: true
-    attribute :identity_strategy,    one_of("slug", "sequence", "port"), optional: true
-    attribute :identity_source,      SettingsText, optional: true
-    attribute :identity_prefix,      SettingsText, optional: true
-    # `pad` (a sequence strategy's zero-padding width, e.g. "C-004" vs "C-4")
-    # is real but unmodeled here, same as identity_source/identity_prefix —
-    # carried opaquely in identity_extra_json below.
-    attribute :identity_extra_json,  CollectionExtra, optional: true
-    attribute :columns,              list_of(Column)
-    attribute :detail_fields,        list_of(DetailField)
-    attribute :detail_field_columns, list_of(DetailFieldColumn)
-    attribute :preconditions,        list_of(Precondition)
-    attribute :field_formats,        list_of(FieldFormat)
     # Carries real, in-use fields this schema doesn't model (e.g. `noun_sing`,
     # `create_label`, `nav_group`) — opaque, same as StateStyle's extra_json.
     attribute :extra_json,           CollectionExtra, optional: true
@@ -136,61 +120,11 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :value, Integer
     end
 
-    # Shared by extra_json and identity_extra_json — both opaque JSON text, no
-    # reason for two wrapper types. A bare `String` fails on an attribute directly.
+    # Opaque JSON text; a bare `String` fails on an attribute directly.
     value_object "CollectionExtra" do
       attribute :value, String
     end
 
-    # A list/table column. `sortable`/`sort_default` are optional (most columns
-    # take the frontend's default). `sort_default` stays a plain String rather
-    # than a closed `one_of` (ADR 0025) — PresentationConfig.validate! checks it.
-    value_object "Column" do
-      attribute :field,        String
-      attribute :sortable,     String, optional: true  # "true"/"false" — see StateStyle.attention's own comment
-      attribute :sort_default, String, optional: true
-      # `head`/`as`/`hop` confirmed live as real, in-use column-level
-      # overrides this schema didn't model — verified-then-opaque, same
-      # reasoning as StateStyle's own extra_json.
-      attribute :extra_json,   String, optional: true
-    end
-
-    # One field the detail panel shows. `state_filter` only applies to an
-    # entity-backed rows field; nothing here enforces that, since it needs the
-    # app's own live IR — PresentationConfig.validate! checks it in Ruby.
-    value_object "DetailField" do
-      attribute :field,        String
-      attribute :display,      String, optional: true
-      attribute :state_filter, String, optional: true
-      # `head`/`as`/`hop` confirmed live as real, in-use detail-field
-      # overrides this schema didn't model — verified-then-opaque, same
-      # reasoning as StateStyle's own extra_json.
-      attribute :extra_json,   String, optional: true
-    end
-
-    # A rows-shaped detail field's sub-column filter, flattened to one row per
-    # (field, column) pair and grouped back by `field` on the way out — the
-    # same flattening Query::AskOption uses for a compound option's parts.
-    value_object "DetailFieldColumn" do
-      attribute :field,  String
-      attribute :column, String
-    end
-
-    value_object "Precondition" do
-      attribute :field, String
-      attribute :state, String
-      # `message` (a custom refusal message override) confirmed live as
-      # real, in-use — verified-then-opaque, same reasoning as
-      # StateStyle's own extra_json.
-      attribute :extra_json, String, optional: true
-    end
-
-    # `format` stays a plain String too — same nested-`one_of` collision.
-    value_object "FieldFormat" do
-      attribute :field,  String
-      attribute :format, String
-    end
-
     command "Declare" do
       role "Console"
       goal "Give one app aggregate a presentation row, before anything is curated on it yet"
@@ -207,10 +141,9 @@ Hecks.bluebook "ConsoleSettings" do
       goal "Name a collection's own nav label"
 
       reference_to Collection
-      attribute :label, SettingsText
+      attribute :label, SettingsText, sets: true
 
-      sets :label
-      emits LabelSet
+      emits CollectionLabeled
     end
 
     command "SetKey" do
@@ -218,10 +151,9 @@ Hecks.bluebook "ConsoleSettings" do
       goal "Override a collection's own nav/route key"
 
       reference_to Collection
-      attribute :key, SettingsText
+      attribute :key, SettingsText, sets: true
 
-      sets :key
-      emits KeySet
+      emits CollectionKeyed
     end
 
     command "SetNavOrder" do
@@ -229,10 +161,9 @@ Hecks.bluebook "ConsoleSettings" do
       goal "Place a collection in the nav"
 
       reference_to Collection
-      attribute :nav_order, SettingsNumber
+      attribute :nav_order, SettingsNumber, sets: true
 
-      sets :nav_order
-      emits NavOrderSet
+      emits CollectionPlaced
     end
 
     command "SetPrimaryField" do
@@ -240,10 +171,9 @@ Hecks.bluebook "ConsoleSettings" do
       goal "Name which field stands in for a whole record"
 
       reference_to Collection
-      attribute :primary_field, SettingsText
+      attribute :primary_field, SettingsText, sets: true
 
-      sets :primary_field
-      emits PrimaryFieldSet
+      emits PrimaryFieldChosen
     end
 
     command "SetListQuery" do
@@ -251,95 +181,232 @@ Hecks.bluebook "ConsoleSettings" do
       goal "Name which of an aggregate's own queries lists its records"
 
       reference_to Collection
-      attribute :list_query, SettingsText
+      attribute :list_query, SettingsText, sets: true
+
+      emits ListQueryChosen
+    end
+
+    command "SetExtra" do
+      role "Console"
+      goal "Carry whatever per-collection fields aren't individually modeled yet (noun_sing, create_label, nav_group, ...)"
+
+      reference_to Collection
+      attribute :extra_json, CollectionExtra, sets: true
+
+      emits CollectionAnnotated
+    end
+  end
+
+  aggregate "CollectionIdentity" do
+    description "How one app aggregate's console assigns its own new records' identity — the field, the strategy (slug, sequence or a port), and the strategy's source and prefix. One consistency boundary: a strategy and its prefix change together or not at all."
+
+    attribute :agg, IdentityText
+
+    identified_by :agg
+
+    attribute :identity_field,       IdentityText, optional: true
+    attribute :identity_strategy,    one_of("slug", "sequence", "port"), optional: true
+    attribute :identity_source,      IdentityText, optional: true
+    attribute :identity_prefix,      IdentityText, optional: true
+    # `pad` (a sequence strategy's zero-padding width, e.g. "C-004" vs "C-4")
+    # is real but unmodeled here, same as identity_source/identity_prefix —
+    # carried opaquely in identity_extra_json below.
+    attribute :identity_extra_json,  IdentityExtra, optional: true
+
+    value_object "IdentityText" do
+      attribute :value, String
+      invariant("names something") { !value.to_s.empty? }
+    end
+
+    value_object "IdentityExtra" do
+      attribute :value, String
+    end
+
+    command "Declare" do
+      role "Console"
+      goal "Give one app aggregate's identity a row, before anything is curated on it yet"
+
+      attribute :agg, IdentityText
+
+      given("a identity names its own aggregate") { !agg.value.to_s.empty? }
 
-      sets :list_query
-      emits ListQuerySet
+      emits CollectionIdentityDeclared
     end
 
     command "SetIdentity" do
       role "Console"
       goal "Name how a collection assigns its own new records' identity"
 
-      reference_to Collection
-      attribute :identity_field,       SettingsText
-      attribute :identity_strategy,    one_of("slug", "sequence", "port")
+      reference_to CollectionIdentity
+      attribute :identity_field,       IdentityText, sets: true
+      attribute :identity_strategy,    one_of("slug", "sequence", "port"), sets: true
 
-      sets :identity_field
-      sets :identity_strategy
       sets :identity_source
       sets :identity_prefix
       sets :identity_extra_json
-      emits IdentitySet
+      emits CollectionIdentified
     end
+  end
 
-    command "SetExtra" do
+  aggregate "CollectionLayout" do
+    description "What one app aggregate's console shows: the table columns, the detail-panel fields (with an optional entity state_filter and a row_columns subset). Every list-shaped piece is rows on this root, never a nested list inside a value object — no value object here can hold a map, and this sidesteps ever finding out whether one can hold a plain list either. Each list is replaced whole, never patched."
+
+    attribute :agg, LayoutText
+
+    identified_by :agg
+
+    attribute :columns,              list_of(Column)
+    attribute :detail_fields,        list_of(DetailField)
+    attribute :detail_field_columns, list_of(DetailFieldColumn)
+
+    value_object "LayoutText" do
+      attribute :value, String
+      invariant("names something") { !value.to_s.empty? }
+    end
+
+    # A list/table column. `sortable`/`sort_default` are optional (most columns
+    # take the frontend's default). `sort_default` stays a plain String rather
+    # than a closed `one_of` (ADR 0025) — PresentationConfig.validate! checks it.
+    value_object "Column" do
+      attribute :field,        String
+      attribute :sortable,     String, optional: true  # "true"/"false" — see StateStyle.attention's own comment
+      attribute :sort_default, String, optional: true
+      # `head`/`as`/`hop` confirmed live as real, in-use column-level
+      # overrides this schema didn't model — verified-then-opaque, same
+      # reasoning as StateStyle's own extra_json.
+      attribute :extra_json,   String, optional: true
+    end
+
+    # One field the detail panel shows. `state_filter` only applies to an
+    # entity-backed rows field; nothing here enforces that, since it needs the
+    # app's own live IR — PresentationConfig.validate! checks it in Ruby.
+    value_object "DetailField" do
+      attribute :field,        String
+      attribute :display,      String, optional: true
+      attribute :state_filter, String, optional: true
+      # `head`/`as`/`hop` confirmed live as real, in-use detail-field
+      # overrides this schema didn't model — verified-then-opaque, same
+      # reasoning as StateStyle's own extra_json.
+      attribute :extra_json,   String, optional: true
+    end
+
+    # A rows-shaped detail field's sub-column filter, flattened to one row per
+    # (field, column) pair and grouped back by `field` on the way out — the
+    # same flattening Query::AskOption uses for a compound option's parts.
+    value_object "DetailFieldColumn" do
+      attribute :field,  String
+      attribute :column, String
+    end
+    command "Declare" do
       role "Console"
-      goal "Carry whatever per-collection fields aren't individually modeled yet (noun_sing, create_label, nav_group, ...)"
+      goal "Give one app aggregate's layout a row, before anything is curated on it yet"
 
-      reference_to Collection
-      attribute :extra_json, CollectionExtra
+      attribute :agg, LayoutText
 
-      sets :extra_json
-      emits CollectionExtraSet
+      given("a layout names its own aggregate") { !agg.value.to_s.empty? }
+
+      emits CollectionLayoutDeclared
     end
 
     command "ReplaceColumns" do
       role "Console"
       goal "Replace a collection's own whole list of table columns"
 
-      reference_to Collection
+      reference_to CollectionLayout
 
       sets :columns
-      emits ColumnsReplaced
+      emits ColumnsArranged
     end
 
     command "ReplaceDetailFields" do
       role "Console"
       goal "Replace a collection's own whole list of detail-panel fields"
 
-      reference_to Collection
+      reference_to CollectionLayout
 
       sets :detail_fields
-      emits DetailFieldsReplaced
+      emits DetailFieldsArranged
     end
 
     command "ReplaceDetailFieldColumns" do
       role "Console"
       goal "Replace every rows-field's own sub-column filter, whole"
 
-      reference_to Collection
+      reference_to CollectionLayout
 
       sets :detail_field_columns
-      emits DetailFieldColumnsReplaced
+      emits DetailFieldColumnsArranged
+    end
+  end
+
+  aggregate "CollectionRules" do
+    description "The rules one app aggregate's console applies: the dispatch preconditions that gate a command on a field's state, and the display format of each field. Each list is replaced whole, never patched."
+
+    attribute :agg, RulesText
+
+    identified_by :agg
+
+    attribute :preconditions,        list_of(Precondition)
+    attribute :field_formats,        list_of(FieldFormat)
+
+    value_object "RulesText" do
+      attribute :value, String
+      invariant("names something") { !value.to_s.empty? }
+    end
+
+    value_object "Precondition" do
+      attribute :field, String
+      attribute :state, String
+      # `message` (a custom refusal message override) confirmed live as
+      # real, in-use — verified-then-opaque, same reasoning as
+      # StateStyle's own extra_json.
+      attribute :extra_json, String, optional: true
+    end
+
+    # `format` stays a plain String too — same nested-`one_of` collision.
+    value_object "FieldFormat" do
+      attribute :field,  String
+      attribute :format, String
+    end
+
+    command "Declare" do
+      role "Console"
+      goal "Give one app aggregate's rules a row, before anything is curated on it yet"
+
+      attribute :agg, RulesText
+
+      given("a rules names its own aggregate") { !agg.value.to_s.empty? }
+
+      emits CollectionRulesDeclared
     end
 
     command "ReplacePreconditions" do
       role "Console"
       goal "Replace a collection's own whole list of dispatch preconditions"
 
-      reference_to Collection
+      reference_to CollectionRules
 
       sets :preconditions
-      emits PreconditionsReplaced
+      emits PreconditionsRestated
     end
 
     command "ReplaceFieldFormats" do
       role "Console"
       goal "Replace a collection's own whole list of field display formats"
 
-      reference_to Collection
+      reference_to CollectionRules
 
       sets :field_formats
-      emits FieldFormatsReplaced
+      emits FieldFormatsChosen
     end
   end
 
+
   # Domain-wide, not per-aggregate: exactly one row, ever, for the whole
   # console. `key` holds a literal constant ("overview") rather than anything
   # chosen, since a creating command still needs some identity to hydrate against.
   aggregate "Overview" do
-    description "The console's own dashboard stat cards, whole. One row, ever — `key` is always the literal 'overview', never chosen. Every stat gets replaced as a whole list on save, the same 'replace whole, never patch one' convention Collection's own columns/detail_fields/preconditions/field_formats already use."
+    description "The console's own dashboard stat cards, whole. One row, ever — `key` is always the literal 'overview', never chosen. Every stat gets replaced as a whole list on save, the same 'replace whole, never patch one' convention CollectionLayout's and CollectionRules' own lists already use."
 
     attribute :key, OverviewKey
 
@@ -381,7 +448,7 @@ Hecks.bluebook "ConsoleSettings" do
       reference_to Overview
 
       sets :stats
-      emits StatsReplaced
+      emits OverviewStatsArranged
     end
   end
 
@@ -399,4 +466,22 @@ Hecks.bluebook "ConsoleSettings" do
     include Collection
     group_by :agg
   end
+
+  read_model "CuratedIdentities" do
+    description "Every CollectionIdentity row, nested by the app aggregate whose records it identifies."
+    include CollectionIdentity
+    group_by :agg
+  end
+
+  read_model "CuratedLayouts" do
+    description "Every CollectionLayout row, nested by the app aggregate whose columns and detail fields it arranges."
+    include CollectionLayout
+    group_by :agg
+  end
+
+  read_model "CuratedRules" do
+    description "Every CollectionRules row, nested by the app aggregate whose preconditions and formats it states."
+    include CollectionRules
+    group_by :agg
+  end
 end

data/lib/hecks/framework/bluebook/framework.hecksagon

@@ -21,3 +21,10 @@ Hecks.hecksagon "Identity" do
   attaches "Governance"
   persisted_by "Memory"
 end
+
+# Privacy's `Keys` port is declared in privacy.ports.hecksagon, beside its adapter binding.
+Hecks.hecksagon "Privacy" do
+  # `Marking.Mark` declares `role "Deployment"` and `Shred` a privacy officer; same reason as Compliance.
+  attaches "Governance"
+  persisted_by "Memory"
+end

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

@@ -2,13 +2,16 @@ Hecks.bluebook "Governance" do
   vision "Organizational authority is explicit, reviewable, and historically explainable."
   supporting
 
-  # What this chapter answers for every attaching domain: the role check at dispatch, boot's
+  # What this bluebook answers for every attaching domain: the role check at dispatch, boot's
   # refusal of an ungoverned `role`, the authorization adapter and the fuzzer's grant
-  # steering read these three verbs from here rather than recognising "Governance" by name.
+  # steering read these verbs from here rather than recognising "Governance" by name. What counts
+  # as live is declared here, as the two `Live` queries, and not decided by the reader.
   provides "authorization",
-           assignments: "RoleAssignment.AssignmentsForActor",
-           grant:       "RoleAssignment.Assign",
-           transitions: "RoleTransition.Allowed"
+           assignments:      "RoleAssignment.AssignmentsForActor",
+           live_assignments: "RoleAssignment.LiveAssignmentsForActor",
+           grant:            "RoleAssignment.Assign",
+           transitions:      "RoleTransition.Allowed",
+           live_transitions: "RoleTransition.LiveAllowed"
 
   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."
@@ -39,8 +42,10 @@ Hecks.bluebook "Governance" do
       invariant("a scope is named") { !value.to_s.empty? }
     end
 
+    # A UTC instant: a date, or a date and time ending in Z. Both read and sort the same way, so
+    # "has it started" and "does it end after it starts" are string comparisons the model can state.
     value_object "Timestamp" do
-      attribute :value, String
+      attribute :value, String, pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}Z)?$'
       invariant("a timestamp is present") { !value.to_s.empty? }
     end
 
@@ -61,9 +66,10 @@ Hecks.bluebook "Governance" do
       goal "Remove organizational authority"
 
       reference_to RoleAssignment
-      attribute :ends_at, Timestamp
+      attribute :ends_at, Timestamp, sets: true
+
+      given("a grant ends no earlier than it starts") { ends_at.value >= starts_at.value }
 
-      sets :ends_at
       emits RoleRevoked
     end
 
@@ -72,6 +78,14 @@ Hecks.bluebook "Governance" do
       attribute :actor_id, IdentityId
       where(actor_id: :actor_id)
     end
+
+    # Live means not yet revoked: a grant whose `ends_at` was never set. The adapter that checks a
+    # role reads this and does not decide liveness itself.
+    query "LiveAssignmentsForActor" do
+      description "Every role an actor holds right now: assigned and not yet revoked."
+      attribute :actor_id, IdentityId
+      where(actor_id: :actor_id, ends_at: nil)
+    end
   end
 
   # Whether role X may act as role Y, which `act_as` needs before a caller dispatches under a
@@ -94,7 +108,7 @@ Hecks.bluebook "Governance" do
     end
 
     value_object "Timestamp" do
-      attribute :value, String
+      attribute :value, String, pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}Z)?$'
       invariant("a timestamp is present") { !value.to_s.empty? }
     end
 
@@ -114,20 +128,28 @@ Hecks.bluebook "Governance" do
       goal "Remove an authorized role transition"
 
       reference_to RoleTransition
-      attribute :ends_at, Timestamp
+      attribute :ends_at, Timestamp, sets: true
+
+      given("a grant ends no earlier than it starts") { ends_at.value >= starts_at.value }
 
-      sets :ends_at
       emits RoleTransitionRevoked
     end
 
-    # Every grant of this pair, current or historical: `where` cannot ask "ends_at is absent",
-    # so the caller reads `ends_at` to tell a live grant from a revoked one. A pair granted
-    # again after a revocation is a second row.
+    # Every grant of this pair, current or historical. A pair granted again after a revocation is
+    # a second row.
     query "Allowed" do
       description "Every role transition granted for this exact pair, current or historical."
       attribute :from_role, RoleName
       attribute :to_role,   RoleName
       where(from_role: :from_role, to_role: :to_role)
     end
+
+    # The grants of this pair that were never revoked: the ones that let one role act as another.
+    query "LiveAllowed" do
+      description "Every role transition granted for this exact pair and not yet revoked."
+      attribute :from_role, RoleName
+      attribute :to_role,   RoleName
+      where(from_role: :from_role, to_role: :to_role, ends_at: nil)
+    end
   end
 end

data/lib/hecks/framework/bluebook/identity.bluebook

@@ -5,7 +5,7 @@ Hecks.bluebook "Identity" do
   # `supporting` (ADR 0025).
   generic
 
-  # What this chapter answers for every attaching domain, declared rather than named as
+  # What this bluebook answers for every attaching domain, declared rather than named as
   # Governance's `provides "authorization"` is. Field mapping lives on the consuming
   # hecksagon's `translates` ACL; Link's reference is `identity`, not `identity_id` or `to:`.
   provides "identity",