homemaker-layout/experiments/usage_map_proposal.yaml

# `usage:` assignments for every corpus room code (homemaker-py-sel).
#
# FOR REVIEW — nothing reads this yet. Once agreed it becomes the input to the
# migration that writes `usage:` into each `patterns.config`.
#
# Usage is an ACCESS-REQUIREMENT class, not a room-name category (Bruno:
# "library corner and staff room are living rooms as they have the same access
# requirements"). What each class does today, in `graph.has_circulation`:
#
#   living   keeps its MOST popular circulation neighbour; not stripped from
#            other rooms, so living spaces may chain to one another.
#   kitchen  as living, plus `fitness.access` accepts living/circulation.
#   bedroom  edges to living/kitchen/bedroom/toilet are REMOVED, so it is
#            reachable only from circulation or outside — a terminal private
#            room, never a route.
#   toilet   edges to outside/living/kitchen/toilet removed.
#   utility  NEW. Same access requirements as `bedroom` today (terminal, never a
#            route) but a DISTINCT declared use — see DESIGN NOTE 1.
#   none     nothing is stripped: the room is fully permeable and the
#            connectivity graph MAY ROUTE THROUGH IT. Correct only for spaces
#            that genuinely are part of the circulation system.
#
# `none` is why this is a bigger change than it looks: 34 of 52 corpus codes
# currently have no class, so a Dental Surgery, a Records Room and a Utilities
# Closet can all serve as corridors today.

living:
  cr1: Common Room with Fireplace
  da1: Dining Area
  en1: TV / Media Room
  gy1: Exercise Room
  l1: Living/Dining/Kitchen
  li1: Library Corner            # ruled: same access requirements as a living room
  lo1: Lounge
  lr1: Common Living Room
  br1: Staff Room                # ruled: same access requirements as a living room
  m: Meeting Room
  gh1: Greenhouse                # ruled: grows plants, but a living area like a conservatory
  ws1: Workshop Space            # ruled CONDITIONALLY — see DESIGN NOTE 3

kitchen:
  k1: Kitchen
  kt1: Staff Kitchenette

bedroom:                          # terminal private room, entered from circulation only
  b1: Master Bedroom
  b2: Second Bedroom
  r: Individual Room
  n: Neighborhood                # ruled: a communal sleeping area, much like a dormitory
  tr1: Treatment Room            # ruled: access requirements of a bedroom
  de1: Dental Surgery
  gp1: GP Consulting Room
  ms1: Minor Surgery Room
  pt1: Physiotherapy Room
  qr1: Counselling Room
  py: Therapy Room
  q1: Quiet Room
  mo1: Manager's Office
  ao1: Admin Office
  em: Staff Office
  of: Staff Office
  ph1: Pharmacy / Dispensary     # ruled: a private room, not public, like an office

toilet:
  t: Bathroom
  t1: Ensuite Bathroom
  t2: Guest Bathroom
  t3: Ground Floor WC
  t9: Public WC
  t10: Staff WC
  tt: Upper Bathroom

utility:                          # terminal, never a circulation route
  la1: Laundry Room              # ruled: utility, not a circulation route
  ut1: Utilities Closet
  me1: Mechanical/Electrical Room  # "Plant / Mechanical Room" in health-centre
  dp1: General Storage
  st1: Ground Floor Storage
  st2: First Floor Storage
  ur1: Ground Floor Storage
  ur2: First Floor Storage
  ur3: Second Floor Storage
  re1: Records Room
  zt1: Sterilisation Room        # ruled: utility — a room for sterilising tools and machinery

none:                             # genuinely part of the circulation system
  ef1: Entrance Foyer
  rc1: Reception                 # "Reception Office" in maple-court — see DESIGN NOTE 4
  wa1: Waiting Room

# --------------------------------------------------------------------------- #
# DESIGN NOTES
# --------------------------------------------------------------------------- #
#
# 1. `utility` IS a distinct value, not an alias for `bedroom`.
#    Ruled: "a utility may have similar requirements to a bedroom, and it may be
#    useful during evolution superposition to treat them as interchangeable
#    before wave function collapse, but they are very different uses."
#    So it maps onto bedroom's edge-stripping today (identical access
#    requirements) while staying separately declared, which gives two things:
#    the config reads truthfully for a bin store, and `usage` becomes a natural
#    axis for `programme.derive_interchange_classes` (§13/§26, homemaker-py-9o5)
#    — bedroom-class and utility-class leaves could be declared interchangeable
#    DURING search and collapse to their real use at scoring time, which is
#    exactly the superposition relaxation that machinery already implements.
#
# 2. Adjacency value survives the connectivity stripping — VERIFIED, no bug.
#    Ruled: "a toilet adjacent to a bedroom or treatment room is a positive even
#    if there is no door, see How Buildings Learn by Stewart Brand, at some point
#    there may be a need to knock it through."
#    `fitness._evaluate_full` runs `check_adjacency` against `graph_base_pre`,
#    the UNFILTERED graph, so a declared `adjacency:` requirement is satisfied by
#    a neighbouring room regardless of what `has_circulation` later strips. The
#    stripping only denies ROUTING (you cannot walk through a bedroom to reach
#    the loo), which is correct. Brand's adaptability positive is therefore
#    already expressible.
#
#    BUT it is only ever scored where a programme DECLARES it, and three of the
#    four real programmes do not:
#      programme-house  t1 -> adjacency: [b1]   declared
#      harbor-house     t (Bathroom, count 6) vs r / n (sleeping)  NOT declared
#      maple-court      t, tt vs r / n                             NOT declared
#      health-centre    t9 / t10 vs tr1 (Treatment Room)           NOT declared
#    Adding those declarations is programme authoring, independent of this bead
#    (filed as homemaker-py-3qj), and would let the search earn the adaptability credit it
#    currently cannot.
#
# 3. `ws1` Workshop Space is building-specific.
#    Ruled: "could be a communal craft room, a living space, or it could be a
#    maintenance area, a utility room, it depends on the building."
#    Both corpus programmes carrying it (harbor-house, maple-court) are communal
#    living facilities, so `living` is the reading here — but this is exactly the
#    case that argues for per-programme declaration rather than a global map.
#    Flip it to `utility` in either file if the intent was a maintenance shop.
#
# 4. Three codes mean different rooms in different programmes: `ph1`
#    (Pharmacy/Dispensary in health-centre, Clinic Room in maple-court), `me1`
#    (Mechanical/Electrical vs Plant/Mechanical), `rc1` (Reception vs Reception
#    Office). Usage is declared per `patterns.config`, so they may legitimately
#    differ — worth confirming it is intended rather than copy-paste drift.
#    NB the assignments above are listed per CODE for review convenience; the
#    migration writes them per FILE, so a code can differ between programmes.
#
# 5. `usage` is a plain ATTRIBUTE of the space definition. No mapping table.
#    An earlier draft proposed a top-level `usage_classes:` table binding
#    author-coined names to engine behaviour (`craft: living`). Withdrawn — it
#    was wrong three ways:
#
#    a) It is the same bug in another costume. An indirect name -> behaviour
#       mapping, living apart from the thing it describes, is exactly what the
#       first-character prefix rule was; §39 exists to remove that shape, not to
#       relocate it into a table.
#
#    b) It is inconsistent with the schema. Every other space property is a
#       plain attribute — name, size, width, proportion, adjacency, level,
#       requires_below, count, share, interchange, co_locate — and no key
#       anywhere in patterns.config is an indirection table. `usage:` belongs
#       beside them.
#
#    c) The need it was meant to serve is already met. "Programmes are building
#       specific" is about what a room is CALLED, and `name:` is already free
#       text: `name: Workshop Space`. What `usage:` records is the room's ACCESS
#       REQUIREMENTS, which are not building-specific — a craft room and a
#       lounge have the same ones, which is the whole reason this key exists.
#       The earlier draft conflated the two.
#
#    So:
#
#        spaces:
#          ws1:
#            name: Workshop Space      # free text, building-specific
#            usage: living             # controlled, drives engine behaviour
#
#    An alias would add nothing anyway: `craft: living` produces no behaviour
#    that `usage: living` does not. The rule that falls out is worth stating —
#    A USAGE VALUE EXISTS IF AND ONLY IF THE ENGINE TREATS IT DIFFERENTLY
#    SOMEWHERE. Config selects among behaviours; it cannot invent them. Adding a
#    genuinely new access class means writing code, not config, and at that
#    point the value joins the controlled set for everyone.
#
#    `utility` passes that test — not on edge-stripping, which is identical to
#    `bedroom` today, but because it is intended to drive
#    derive_interchange_classes (NOTE 1). Distinct behaviour in a second
#    subsystem is a real difference; an alias is not.