{
  "Actor": {
    "name": "Actor",
    "version": "1.0.2",
    "description": "The ability to act: an object that composes Actor can be assigned work, hold a role, own a record and appear in\na record's history as the one who made a change. User composes it as a person; Agent composes it as an agent.\n\nAn agent is an actor, not a user. In OODS an object is what its traits make it, so an AI agent that acts\ninside a product is an object of its own, and what it shares with a person's account is this trait. Platforms that\nstored their agents as users did so because their roles and audit logs could point only at users; here the places\nthat name an actor accept any object that composes Actor:\n\n  a history entry   actor_id and actor_kind name who acted (Stateful's state_history, Auditable's audit_log)\n  a membership      actor_id with actor_kind holds a role in an organization (Authable's membership_records)\n  a grant           a Grant's seats (the Mandate trait): who asked for it, gave it, holds it and ended it\n  an owner          Ownerable's owner_id with owner_type\n\nThe kind is a parameter, never a record field: every record of an object is the same kind of actor, so a User's\nrecords and screens are unchanged by composing it. An actor of kind agent is marked \"Agent\" in\nlist, card and detail views, so no one reads an agent's record as a person's. actor_kind on a history entry or a\nmembership uses the same three words.",
    "category": "core",
    "tags": [
      "actor",
      "identity",
      "agent",
      "delegation",
      "accountability"
    ],
    "contexts": [],
    "viewExtensions": [],
    "parameters": [
      {
        "name": "kind",
        "type": "string",
        "required": true,
        "description": "What every record of this object is when it acts: person (someone's own account), agent (software that acts,\non its own behalf or for someone) or system (the product itself, such as a scheduled job). An agent is marked\n\"Agent\" in lists, cards and its own page.\n",
        "default": "person",
        "validation": {
          "enum": [
            "person",
            "agent",
            "system"
          ]
        }
      }
    ],
    "schema": {},
    "semantics": {},
    "tokens": {},
    "dependencies": [],
    "metadata": {
      "created": "2026-11-07",
      "updated": "2026-11-14",
      "owners": [
        "Core team",
        "Identity team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "Actor adds no interactive control.",
        "screenreader": "The badge exposes the word \"Agent\" as text."
      },
      "regionsUsed": [],
      "examples": [
        "User",
        "Agent"
      ],
      "references": [
        "Microsoft Entra Agent ID: agentIdentity inherits servicePrincipal, with owners and a required sponsor",
        "draft-wzdk-scim-agent-resource-00: an Agent resource beside User and Group, with optional owners",
        "GitHub GraphQL: the Actor interface, implemented by User, Bot, Organization, Mannequin and EnterpriseUserAccount",
        "RFC 8693 §4.1: the act (actor) claim names the acting party to whom authority has been delegated"
      ]
    },
    "objects": [
      "Agent",
      "User"
    ],
    "source": "traits/core/Actor.trait.yaml"
  },
  "Addressable": {
    "name": "Addressable",
    "version": "1.0.0",
    "description": "Canonical multi-role address trait with validation metadata, geocoding, and international formatting hooks.\nProvides a single, reusable capability for billing, shipping, warehouse, and office addresses.",
    "category": "core",
    "tags": [
      "address",
      "location",
      "validation",
      "delivery"
    ],
    "contexts": [
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "AddressSummaryBadge",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "field": "default_address_role"
        }
      },
      {
        "component": "AddressCollectionPanel",
        "context": "detail",
        "position": "main",
        "priority": 60,
        "props": {
          "field": "addresses",
          "roleField": "address_roles",
          "defaultRoleField": "default_address_role",
          "roleParameter": "roles"
        }
      },
      {
        "component": "AddressEditor",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "field": "addresses",
          "roleParameter": "roles",
          "allowDynamicParameter": "allowDynamicRoles",
          "defaultRoleField": "default_address_role"
        }
      }
    ],
    "parameters": [
      {
        "name": "roles",
        "type": "string[]",
        "required": true,
        "description": "Ordered list of supported address roles (billing, shipping, warehouse, etc.).",
        "default": [
          "billing",
          "shipping"
        ],
        "validation": {
          "minItems": 1,
          "maxItems": 16,
          "uniqueItems": true,
          "items": {
            "pattern": "^[a-z0-9._-]+$",
            "minLength": 2,
            "maxLength": 32
          }
        }
      },
      {
        "name": "defaultRole",
        "type": "string",
        "required": false,
        "description": "Preferred role returned when consumers omit a role argument.",
        "validation": {
          "enumFromParameter": "roles"
        }
      },
      {
        "name": "allowDynamicRoles",
        "type": "boolean",
        "required": false,
        "description": "Allow runtime creation of roles that are not pre-declared in roles.",
        "default": false
      }
    ],
    "schema": {
      "address_roles": {
        "type": "string[]",
        "required": true,
        "description": "Ordered list of roles that currently have address entries.",
        "default": []
      },
      "default_address_role": {
        "type": "string",
        "required": false,
        "description": "Role surfaced in UI contexts when one address must be highlighted.",
        "validation": {
          "enumFromParameter": "roles"
        }
      },
      "addresses": {
        "type": "AddressableEntry[]",
        "required": false,
        "description": "Collection of { role, address, metadata } entries keyed by role.",
        "default": []
      }
    },
    "semantics": {
      "addresses": {
        "semantic_type": "location.address.collection",
        "token_mapping": "tokenMap(location.address.collection)",
        "ui_hints": {
          "component": "AddressCollection",
          "roleParameter": "roles",
          "defaultRoleField": "default_address_role"
        }
      },
      "default_address_role": {
        "semantic_type": "location.address.default_role",
        "token_mapping": "tokenMap(location.address.default_role)",
        "ui_hints": {
          "component": "AddressRoleBadge",
          "parameterSource": "defaultRole"
        }
      },
      "address_roles": {
        "semantic_type": "location.address.roles",
        "token_mapping": "tokenMap(location.address.roles)",
        "ui_hints": {
          "component": "AddressRolePills"
        }
      }
    },
    "tokens": {
      "location.address.card.bg": "var(--sys-surface-raised)",
      "location.address.card.border": "var(--sys-border-subtle)",
      "location.address.role.text": "var(--sys-text-muted)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-17",
      "owners": [
        "Core team",
        "Platform team"
      ],
      "maturity": "experimental",
      "accessibility": {
        "keyboard": "AddressEditor respects standard focus order and announces role changes.",
        "screenreader": "AddressCollection surfaces headings per role and announces validation status."
      },
      "regionsUsed": [
        "list",
        "detail",
        "form"
      ],
      "examples": [
        "User",
        "Organization"
      ],
      "references": [
        "R21.1 Canonical Model for Address/Location Systems"
      ]
    },
    "objects": [
      "Organization",
      "User"
    ],
    "source": "traits/core/Addressable.trait.yaml"
  },
  "Approvable": {
    "name": "Approvable",
    "version": "1.1.1",
    "description": "The ability to be approved: the thing's own rule for which change needs which level of yes, from how many and from\nwhom, and its outcome, worked out from the approvals that still stand. The approvals themselves are records of\ntheir own (the Approval object, through the Decision trait): one ask to one actor that becomes their answer.\n\nThe rule is the parameters. `levels` names the levels of yes the product declares, least deliberate first, as Decision does on\nthe Approval; `levelDefinitions` says what each one is, in six short texts; `requiredLevels` says which change (a\nstate the thing moves to, or a named action) needs which level; `approvalsNeeded`, `askerMayAnswer`,\n`agentLevels` and `lapsesOnChange` say how many, whether the asker may answer, which levels an agent's yes may\nsatisfy, and whether a yes lapses when the thing changes. `inAdvance` names the changes a grant's standing yes may\nallow in advance, where the product lets a yes given earlier stand for one asked now; it is empty by default, so\nevery change the rule names is asked each time. The definitions are kept with the rule; no screen changes by level.\n\nThe outcome is two read-only fields: `approval_state`, under a name of its own so it never collides with the\nlifecycle's `status`, and `approval_summary`, one kept line (\"Approved by Ruth Adeyemi · version 3 · 2 Nov\").\nThe product's own code works the outcome out from the approvals and writes both fields; they are kept off the\nthing's form and shown on its detail page. The summary restates the Approval records, since a thing's own page lists\nits approvals only where the thing declares that list (metadata.relatedLists), and no shipped object does.\n\nOODS Foundry shows the outcome; it does not work it out. It does not count approvals, check who may approve,\nexpire an ask, lock the thing or stop a change.",
    "category": "core",
    "tags": [
      "approval-rule",
      "approval-outcome",
      "declared-levels"
    ],
    "contexts": [
      "detail"
    ],
    "viewExtensions": [
      {
        "component": "StatusBadge",
        "context": "detail",
        "position": "main",
        "priority": 58,
        "props": {
          "statusField": "approval_state",
          "emphasis": "subtle",
          "showIcon": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 57,
        "props": {
          "field": "approval_summary"
        }
      }
    ],
    "parameters": [
      {
        "name": "levels",
        "type": "string[]",
        "required": true,
        "description": "The levels of yes the product declares, least deliberate first, each named for the kind of yes asked for. Every\nlevel the rule\nnames is one of these, and the approvals of this thing are asked at these levels (Decision's `levels`).\n",
        "default": [
          "acknowledgement",
          "review",
          "approval",
          "sign_off"
        ]
      },
      {
        "name": "levelDefinitions",
        "type": "Record<string, LevelDefinition>",
        "required": false,
        "description": "What each level is, keyed by its name: who may give it, what it permits, what must be in front of the person,\nwhat a wrong one costs, how deliberate the act is, and when it lapses. Each key is a declared level. A product\ndeclares its own, beside its own levels; the four example levels' definitions are in this trait's metadata.\n",
        "default": {}
      },
      {
        "name": "requiredLevels",
        "type": "Record<string, string>",
        "required": false,
        "description": "Which change needs which level: each key is a change (a lifecycle state the thing moves to, such as published,\nor a named action, such as resend), each value a declared level. Under this rule your product requires no approval for an unlisted change.\n",
        "default": {}
      },
      {
        "name": "approvalsNeeded",
        "type": "Record<string, number>",
        "required": false,
        "description": "How many eligible approvers your product requires at each named level. The map starts empty.\nFor a level with no count, the rule calls for one eligible approver. Your product checks and counts the answers.\n",
        "default": {}
      },
      {
        "name": "askerMayAnswer",
        "type": "boolean",
        "required": false,
        "description": "Whether your product permits the asker to give the yes. The default is false. Your product checks who answered.",
        "default": false
      },
      {
        "name": "agentLevels",
        "type": "string[]",
        "required": false,
        "description": "The levels for which your product accepts an agent’s yes. The default list is empty. Your product checks who answered.",
        "default": []
      },
      {
        "name": "lapsesOnChange",
        "type": "boolean",
        "required": false,
        "description": "Whether your product marks an earlier yes out of date when the thing changes. OODS Foundry keeps the setting.",
        "default": true
      },
      {
        "name": "inAdvance",
        "type": "string[]",
        "required": false,
        "description": "The changes a standing yes, given in advance under a grant, may allow without a person being asked at the time.\nEach is a change `requiredLevels` names; where the rule declares two or more levels, none needs the last, most\ndeliberate one, which is always asked. Empty by default, so every change the rule names is asked each time. The product checks a standing yes\nagainst its grant's terms; OODS Foundry keeps the setting and shows the outcome.\n",
        "default": []
      },
      {
        "name": "outcomes",
        "type": "string[]",
        "required": true,
        "description": "The outcomes `approval_state` can hold, as the product works them out: not required, waiting, approved,\ndeclined, out of date by default. Not required means the rule asks for no approval for this change.\nNot needed is the ending of a particular Approval that is no longer needed. A rule that opens changes in advance may add allowed in advance\n(`allowed_in_advance`): the change needed a yes, and a grant's standing yes gave it, with no one asked this time.\n",
        "default": [
          "not_required",
          "waiting",
          "approved",
          "declined",
          "out_of_date"
        ]
      }
    ],
    "schema": {
      "approval_state": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The outcome, worked out by the product from the approvals that still stand and written here. Named apart from\nStateful's `status`, so a thing keeps its lifecycle and its approval outcome side by side. Read-only: it is shown\non the detail page and kept off the form.\n",
        "validation": {
          "enumFromParameter": "outcomes"
        }
      },
      "approval_summary": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "One kept line saying what the outcome rests on (\"Approved by Ruth Adeyemi · version 3 · 2 Nov\"), or why no\napproval was asked. It restates the Approval records, since a thing's own page lists its approvals only where the\nthing declares that list (metadata.relatedLists), and no shipped object does. Read-only.\n",
        "validation": {
          "maxLength": 240
        }
      }
    },
    "semantics": {
      "approval_state": {
        "semantic_type": "approval.outcome",
        "token_mapping": "tokenMap(status.state.*)",
        "ui_hints": {
          "component": "StatusBadge",
          "showIcon": true
        }
      },
      "approval_summary": {
        "semantic_type": "approval.outcome.summary",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Approvals"
        }
      }
    },
    "tokens": {},
    "dependencies": [],
    "metadata": {
      "created": "2026-11-11",
      "updated": "2026-11-14",
      "owners": [
        "Core team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "Approvable adds no interactive control; its outcome renders as text.",
        "screenreader": "The outcome is announced as visible text through StatusBadge, never by colour alone, with its summary as labelled text."
      },
      "regionsUsed": [
        "detail"
      ],
      "levelExamples": {
        "acknowledgement": {
          "who": "Anyone the thing is shown to",
          "permits": "Nothing; it records that the person has seen it",
          "shown": "The thing, as it is now",
          "cost": "Little; a missed one is asked again",
          "act": "One step",
          "lapses": "Never; it records a moment"
        },
        "review": {
          "who": "Someone who knows the subject",
          "permits": "Nothing on its own; it counts toward an approval",
          "shown": "The thing and what changed",
          "cost": "A mistake that someone else may still catch",
          "act": "A careful read, then one step",
          "lapses": "When the thing changes"
        },
        "approval": {
          "who": "The person whose decision it is",
          "permits": "The change it was asked for",
          "shown": "Exactly what will change",
          "cost": "The change happens when it should not",
          "act": "A deliberate yes or no",
          "lapses": "When the thing changes, or once it is used"
        },
        "sign_off": {
          "who": "The person who answers for the result",
          "permits": "The thing to go out under their name",
          "shown": "The exact version, and what the yes means",
          "cost": "A person answers for something they did not mean to",
          "act": "The most deliberate, with its meaning written down",
          "lapses": "Never for that version; a new version needs a new sign-off"
        }
      },
      "examples": [
        "Transaction",
        "Article"
      ],
      "references": [
        "Gerrit: Code-Review +1 'Looks good to me, but someone else must approve' and +2 'Looks good to me, approved'",
        "Docusign: 'Needs to View' recipients, and Part 11 signing that asks the signer for a reason",
        "21 CFR Part 11 and eIDAS: a signature bound to the content and its meaning"
      ]
    },
    "objects": [
      "Article",
      "Transaction"
    ],
    "source": "traits/core/Approvable.trait.yaml"
  },
  "Archivable": {
    "name": "Archivable",
    "version": "2.0.0",
    "description": "Provides archival lifecycle management with configurable retention, restoration, audit\ntracking, and compliance metadata. Archivable manages the full archive-restore-purge\nlifecycle, including soft-delete with configurable duration before hard deletion,\npartial restoration support, and per-archive compliance tagging.\n\nObjects composing Archivable can be soft-deleted (moved to an \"archived\" state with\nfull data retention), restored within a configurable window, or permanently purged\nafter the retention period expires. The trait tracks who archived the entity, why,\nand through what method (manual, automated, policy) for audit trail completeness.",
    "category": "lifecycle",
    "tags": [
      "lifecycle",
      "archival",
      "retention",
      "compliance",
      "audit",
      "soft-delete"
    ],
    "contexts": [
      "card",
      "detail",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "ArchivedRowOverlay",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "archivedField": "is_archived",
          "style": "grayed",
          "showBadge": true,
          "separateTab": true,
          "tabLabel": "Archived"
        }
      },
      {
        "component": "ArchiveSummary",
        "context": "detail",
        "position": "top",
        "priority": null,
        "props": {
          "hideWhenDefault": true,
          "archivedField": "is_archived",
          "archivedAtField": "archived_at",
          "restoredAtField": "restored_at",
          "reasonField": "archive_reason",
          "archivedByField": "archived_by",
          "metadataField": "archive_metadata",
          "retainHistoryParameter": "retainHistory",
          "restoreWindowParameter": "restoreWindowDays",
          "allowPartialRestoreParameter": "allowPartialRestore"
        }
      },
      {
        "component": "ArchivePill",
        "context": "card",
        "position": "before",
        "priority": null,
        "props": {
          "field": "is_archived",
          "archivedAtField": "archived_at",
          "hideWhenFalse": true
        }
      }
    ],
    "parameters": [
      {
        "name": "gracePeriodDays",
        "type": "number",
        "required": false,
        "description": "Number of days after archival before permanent deletion (hard-delete) occurs.",
        "default": 30,
        "validation": {
          "minimum": 0,
          "maximum": 365
        }
      },
      {
        "name": "retainHistory",
        "type": "boolean",
        "required": false,
        "description": "Whether archival retains a readable change history that can be restored.",
        "default": true
      },
      {
        "name": "restoreWindowDays",
        "type": "number",
        "required": false,
        "description": "Maximum number of days archived entities can be restored when history is retained.\nAfter this window, restoration is no longer possible even if the entity hasn't been\nhard-deleted yet.\n",
        "validation": {
          "minimum": 0,
          "maximum": 365
        }
      },
      {
        "name": "softDeleteDuration",
        "type": "number",
        "required": false,
        "description": "Days the entity remains in soft-deleted state before automatic hard deletion.\nDistinct from gracePeriodDays: gracePeriodDays is the notification/warning window,\nwhile softDeleteDuration is the total retention period. When set, a background\nprocess purges entities where (archived_at + softDeleteDuration) has passed.\n",
        "default": 90,
        "validation": {
          "minimum": 0,
          "maximum": 3650
        }
      },
      {
        "name": "allowPartialRestore",
        "type": "boolean",
        "required": false,
        "description": "When true, archived entities can be partially restored — selecting which fields\nor related data to bring back rather than restoring the entire entity. Useful for\nlarge objects where only specific sections need to be recovered (e.g., restoring\na contract's terms but not its expired billing data).\n",
        "default": false
      }
    ],
    "schema": {
      "is_archived": {
        "type": "boolean",
        "required": true,
        "description": "Flag indicating whether the entity is currently archived (soft-deleted).",
        "default": false
      },
      "archived_at": {
        "type": "datetime?",
        "required": false,
        "description": "Timestamp for when the entity entered the archived state."
      },
      "restored_at": {
        "type": "datetime?",
        "required": false,
        "description": "Timestamp for when the entity was most recently restored from an archived state."
      },
      "archive_reason": {
        "type": "string",
        "required": false,
        "description": "Human-readable narrative describing why the entity was archived.",
        "validation": {
          "maxLength": 500
        }
      },
      "archived_by": {
        "type": "string",
        "required": false,
        "description": "User ID or system identifier of the actor who archived this entity.\nSet to \"system\" for automated/policy-driven archival. Supports audit trail queries\nlike \"show all entities archived by user X\" or \"show all auto-archived entities\".\n"
      },
      "archive_metadata": {
        "type": "object",
        "required": false,
        "description": "Structured metadata about the archival action for compliance and audit purposes.\n\nProperties:\n  - method: \"manual\" | \"automated\" | \"policy\" — how the archive was triggered\n  - compliance_tags: string[] — regulatory labels (e.g., [\"GDPR\", \"SOX\", \"HIPAA\"])\n  - retention_policy_id: string — reference to the retention policy that triggered archival\n  - original_status: string — the Stateful status before archival\n  - related_entity_count: number — count of related entities also archived (cascade)\n"
      },
      "restoration_metadata": {
        "type": "object",
        "required": false,
        "description": "Metadata about the most recent restoration action.\n\nProperties:\n  - restored_by: string — user ID or \"system\"\n  - restored_fields: string[] — when partial restore, which fields were restored\n  - restoration_reason: string — why the entity was restored\n  - restored_from_snapshot: boolean — whether restored from a point-in-time snapshot\n"
      }
    },
    "semantics": {
      "is_archived": {
        "semantic_type": "status.archive.state",
        "token_mapping": "tokenMap(status.archive.*)",
        "ui_hints": {
          "component": "ArchiveBadge",
          "showIcon": true
        }
      },
      "archived_at": {
        "semantic_type": "status.archive.timestamp",
        "token_mapping": "tokenMap(status.archive.timestamp)",
        "ui_hints": {
          "component": "TimelineTimestamp"
        }
      },
      "restored_at": {
        "semantic_type": "status.archive.restore_timestamp",
        "token_mapping": "tokenMap(status.archive.restore)",
        "ui_hints": {
          "component": "TimelineTimestamp"
        }
      },
      "archive_reason": {
        "semantic_type": "status.archive.reason",
        "token_mapping": "tokenMap(status.archive.reason)",
        "ui_hints": {
          "component": "ArchiveReason",
          "maxLength": 500
        }
      },
      "archived_by": {
        "semantic_type": "status.archive.actor",
        "token_mapping": "tokenMap(status.archive.actor)",
        "ui_hints": {
          "component": "ActorLabel"
        }
      },
      "archive_metadata": {
        "semantic_type": "status.archive.compliance",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "ArchiveCompliancePanel"
        }
      },
      "restoration_metadata": {
        "semantic_type": "status.archive.restoration",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "RestorationSummary"
        }
      }
    },
    "tokens": {
      "status.archive.primary.bg": "var(--status-archive-bg)",
      "status.archive.primary.text": "var(--status-archive-text)",
      "status.archive.primary.border": "var(--sys-border-default)",
      "status.archive.timestamp.text": "var(--text-subtle)",
      "status.archive.reason.text": "var(--text-default)",
      "status.archive.reason.bg": "var(--sys-surface-neutral)",
      "status.archive.overlay.bg": "var(--sys-surface-disabled)",
      "status.archive.overlay.opacity": "0.6",
      "status.archive.actor.text": "var(--sys-text-secondary)",
      "status.archive.compliance.badge.bg": "var(--sys-status-info-surface)",
      "status.archive.compliance.badge.text": "var(--sys-status-info-text)"
    },
    "dependencies": [
      "Stateful"
    ],
    "metadata": {
      "created": "2025-10-12",
      "updated": "2026-02-28",
      "owners": [
        "Lifecycle team",
        "Compliance team"
      ],
      "maturity": "stable",
      "accessibility": {
        "keyboard": "Archive/Restore actions are triggered via buttons that are keyboard-focusable and\nactivated with Enter/Space. Confirmation dialogs trap focus until dismissed.\n",
        "screenreader": "ArchiveBadge announces \"Archived\" or \"Active\" state. ArchiveSummary announces\narchive date, reason, actor, and remaining restore window. ArchivedRowOverlay\napplies aria-hidden=false to ensure archived rows remain accessible but are\nannounced as \"Archived: [entity name]\" to screen readers.\n",
        "listPresentation": "Archived items in list view are visually dimmed (opacity: 0.6) and optionally\nmoved to a separate \"Archived\" tab. Both presentations maintain keyboard\nnavigability and screen reader access.\n"
      },
      "regionsUsed": [
        "list",
        "detail",
        "card"
      ],
      "examples": [
        "Contract",
        "Product Listing",
        "User Account",
        "Subscription"
      ],
      "references": [
        "Trait Engine Spec v0.1 section 2",
        "GDPR Article 17 — Right to Erasure (soft-delete as intermediate step)"
      ]
    },
    "objects": [
      "Subscription",
      "Transaction"
    ],
    "source": "traits/lifecycle/Archivable.trait.yaml"
  },
  "Assessable": {
    "name": "Assessable",
    "version": "1.1.0",
    "description": "Records what an assessment concluded about a record — its result state — as something other than a\nverdict colour.\n\nA result is not binary. An accessibility engine returns four kinds of answer for every rule on every\npage: it found a violation, it found nothing wrong, it could not decide and a person must look, or the\nrule does not apply there. A fifth is the one engines drop: the check never ran. Lighthouse carries the\nsame shape as score display modes (binary, manual, notApplicable, error). A real capture run records\nall four axe answers — violations as items, and needs-review, passing and not-applicable as page-level\ncounts (28, 2,029 and 1,531) — and Deque warns that implementations drop the incomplete ones. That is\nwhy this is its own trait rather than a Stateful state set: it is not a lifecycle a record moves\nthrough, it is what one reading concluded, and the non-verdicts are the part most often lost.\n\nThe rule that matters is visual. A result state renders as its OWN visual family, never the severity\nfamily: never red, never green, never scored. The moment \"needs review\" looks like a failure, someone\nreports it as one; the moment \"passed\" looks like a success badge, a count of 2,029 passes reads as a\ngrade. The composer enforces it (`enforceResultStateFamily`): every StatusBadge or Badge bound to\n`result_state` carries the result tone from @oods/component-contracts, and a component that cannot\ncarry a tone is refused (OODS-V211). A spec fails if any theme scope resolves that tone to a severity\ncolour.\n\nThe field is `result_state`, not `status`, so an object can carry a lifecycle through Stateful and a\nresult through this trait without the two colliding (the Supersedable precedent). Severity is a\nseparate fact about a violation (Finding.impact) and is never folded into the result state.\n\nArtifact assessments also record measured (the measurement ran), measured_zero (it ran and found\nnone) and unknown (the historical record contains no result). A zero is evidence of measurement,\nnever a missing check. These states use the same neutral family and carry no inferred grade.\n\nNot adopted, with the reason: low-confidence (no capture artifact carries a confidence for a result; the\nConfidence-bearing trait is not authored until a screen needs it); Lighthouse's informative (it states\nno verdict and no capture record carries one); any numeric score (a score is a verdict colour in another\nform).",
    "category": "core",
    "tags": [
      "assessment",
      "result",
      "non-verdict",
      "accessibility",
      "evidence"
    ],
    "contexts": [
      "card",
      "detail",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "StatusBadge",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "statusField": "result_state",
          "domain": "result",
          "emphasis": "subtle",
          "showIcon": false
        }
      },
      {
        "component": "StatusBadge",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "statusField": "result_state",
          "domain": "result",
          "emphasis": "subtle",
          "showIcon": false
        }
      },
      {
        "component": "StatusBadge",
        "context": "detail",
        "position": "main",
        "priority": 72,
        "props": {
          "statusField": "result_state",
          "domain": "result",
          "emphasis": "subtle",
          "showIcon": false
        }
      }
    ],
    "parameters": [
      {
        "name": "recordedStates",
        "type": "string[]",
        "required": true,
        "description": "The result states the source of truth writes as items. Current capture evidence writes violations\nand needs-review items; historical counts alone never become invented findings. Artifact indices\ndeclare measured results separately from their absence.\n",
        "default": [
          "violation",
          "passed",
          "needs_review",
          "not_applicable",
          "not_measured",
          "measured",
          "measured_zero",
          "unknown"
        ]
      }
    ],
    "schema": {
      "result_state": {
        "type": "string",
        "required": true,
        "description": "What the assessment concluded for this record: violation (it measured a failure), passed (it measured\nand found none), needs_review (it could not decide — axe incomplete, Lighthouse manual), not_applicable\n(the rule does not apply here), not_measured (the check did not run). An absent value is never read as\npassed. Measured_zero means a completed measurement found none; unknown means no recorded result.\n",
        "validation": {
          "enum": [
            "violation",
            "passed",
            "needs_review",
            "not_applicable",
            "not_measured",
            "measured",
            "measured_zero",
            "unknown"
          ]
        }
      }
    },
    "semantics": {
      "result_state": {
        "semantic_type": "assessment.result.state",
        "token_mapping": "tokenMap(assessment.result.*)",
        "ui_hints": {
          "component": "StatusBadge",
          "showIcon": false
        }
      }
    },
    "tokens": {
      "assessment.result.tone": "neutral"
    },
    "dependencies": [],
    "metadata": {
      "created": "2026-09-18",
      "updated": "2026-09-20",
      "owners": [
        "Core team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "The result state adds no interactive control; it renders as text beside the record.",
        "screenreader": "Announced as its visible wording (\"Needs review\", \"Not applicable\"), never by colour, and never as a\nstatus of the record's lifecycle.\n"
      },
      "regionsUsed": [
        "list",
        "card",
        "detail"
      ],
      "examples": [
        "Finding"
      ],
      "references": [
        "objects/provenance.v1.json#/references/ref-b9c43cb31221 — the four axe answers on run 6e435ce7, three of them as counts only",
        "https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#results-object — passes, violations, incomplete, inapplicable",
        "https://github.com/GoogleChrome/lighthouse/blob/main/docs/understanding-results.md — scoreDisplayMode"
      ]
    },
    "objects": [],
    "source": "traits/core/Assessable.trait.yaml"
  },
  "Assignment": {
    "name": "Assignment",
    "version": "1.0.0",
    "description": "The record of one ask to one person or agent to do one piece of work, and what became of it: who asked, and for\nwhom; who is doing it; exactly what was asked; what the work is about; what it waits on; where it came from; and\nhow it ended. A task is an ask, not a ticket: the thing the work is about (an invoice, a payment, an issue) stays\nthe product's own record, and the task points at it. The Task object composes this trait, and the importer\nproposes it for another system's record of work, so every field lives here and a proposal can bind what the\nsource has.\n\nThe state of the work is not a field of this trait. It is the record's own lifecycle, through Stateful: for a\nTask, not started, working, needs input, waiting, paused, outcome unknown, and its five endings. A changed ask is\na new task. Handing the whole of the work on ends this one and starts another that names it as the one it came\nfrom; asking for help with a part starts another while this one waits.\n\nA reference to a person, an agent, a task or a thing is an id and a kept name. The name is kept on the record, so\nit still reads after the person leaves or the thing is deleted, and the record's rows show it in place of the id;\nthe closed Reference details block lists the ids themselves. The kinds are the Actor trait's words: who asked can\nbe a person, an agent or a system (an automation); the one doing the work is a person or an agent. No field says\nwhat the one doing the work may do: their authority lives on their own record, a person's account and roles, an\nagent's rules and any grant it holds from the one the work is for.\n\nOODS Foundry keeps and shows this record. It does not run, retry, pause, cancel or time out the work, check who may\ndo it, or keep the try count, what a task waits on or the first ask true.",
    "category": "core",
    "tags": [
      "task-record",
      "work-record",
      "actor-reference",
      "kept-ask"
    ],
    "contexts": [
      "card",
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "LabelCell",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "field": "asked_of_id",
          "description": "Doing it",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "LabelCell",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "field": "waiting_on_id",
          "description": "Waiting on",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "LabelCell",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "field": "asked_of_id",
          "description": "Doing it",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "LabelCell",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "field": "waiting_on_id",
          "description": "Waiting on",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 80,
        "props": {
          "field": "instruction"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 79,
        "props": {
          "field": "subject_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 78,
        "props": {
          "field": "subject_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 77,
        "props": {
          "field": "subject_type",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 76,
        "props": {
          "field": "requested_by_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 75,
        "props": {
          "field": "requested_by_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 74,
        "props": {
          "field": "requested_by_kind",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 73,
        "props": {
          "field": "requested_for_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 72,
        "props": {
          "field": "requested_for_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 71,
        "props": {
          "field": "asked_of_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 70,
        "props": {
          "field": "asked_of_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 69,
        "props": {
          "field": "asked_of_kind",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 68,
        "props": {
          "field": "due_at",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 67,
        "props": {
          "field": "waiting_on_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 66,
        "props": {
          "field": "waiting_on_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 65,
        "props": {
          "field": "waiting_on_type",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 64,
        "props": {
          "field": "result",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 63,
        "props": {
          "field": "tries",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 62,
        "props": {
          "field": "last_try",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 61,
        "props": {
          "field": "parent_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 60,
        "props": {
          "field": "parent_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 59,
        "props": {
          "field": "origin_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 58,
        "props": {
          "field": "origin_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 80,
        "props": {
          "field": "instruction"
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 79,
        "props": {
          "field": "requested_by_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 78,
        "props": {
          "field": "requested_by_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 77,
        "props": {
          "field": "requested_for_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 76,
        "props": {
          "field": "requested_for_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 75,
        "props": {
          "field": "asked_of_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 74,
        "props": {
          "field": "asked_of_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Input",
        "context": "form",
        "position": "main",
        "priority": 60,
        "props": {
          "field": "result"
        }
      },
      {
        "component": "Input",
        "context": "form",
        "position": "main",
        "priority": 59,
        "props": {
          "field": "due_at"
        }
      },
      {
        "component": "Input",
        "context": "form",
        "position": "main",
        "priority": 58,
        "props": {
          "field": "waiting_on_name"
        }
      }
    ],
    "parameters": [],
    "schema": {
      "instruction": {
        "type": "string",
        "required": true,
        "readOnly": true,
        "description": "Exactly what was asked, in one line (\"Count the flour and butter in stock before Monday's supplier order\"). It\nis written once: a changed ask is a new task.\n",
        "validation": {
          "maxLength": 240
        }
      },
      "requested_by_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who asked for the work, by the id the product knows them by. An agent may ask, and may ask itself."
      },
      "requested_by_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who asked, as shown (\"Billing Agent\"). Kept on the record."
      },
      "requested_by_kind": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What kind of actor asked (person, agent or system), as the Actor trait names them.",
        "validation": {
          "enum": [
            "person",
            "agent",
            "system"
          ]
        }
      },
      "requested_for_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who the work is for, the person or organization it serves."
      },
      "requested_for_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who the work is for, as shown (\"Tidewater Co-op\"). Kept on the record."
      },
      "asked_of_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who is doing the work, by the id the product knows them by. One record is one ask to one actor, and after the work\nends this still names the one who was asked to do it.\n"
      },
      "asked_of_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who is doing the work, or did it, as shown (\"Billing Agent\"). Kept on the record."
      },
      "asked_of_kind": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What kind of actor is doing the work, a person or an agent, as the Actor trait names them.",
        "validation": {
          "enum": [
            "person",
            "agent"
          ]
        }
      },
      "subject_type": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What kind of thing the work is about (\"Transaction\", \"Invoice\"). A task can be about nothing on record."
      },
      "subject_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The thing the work is about, by the id the product calls it by (a payment's reference)."
      },
      "subject_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The thing the work is about, as shown. Kept on the record, so it still reads after the thing is deleted."
      },
      "due_at": {
        "type": "datetime",
        "required": false,
        "description": "When the work is due, when someone sets a date.",
        "validation": {
          "format": "date-time"
        }
      },
      "waiting_on_type": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What kind of thing the work waits on, which says what kind of wait it is: an Approval, a person, another task,\nor something outside, such as a payment at the bank. Set only while the work needs input or waits.\n"
      },
      "waiting_on_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What the work waits on, by the id the product knows it by."
      },
      "waiting_on_name": {
        "type": "string",
        "required": false,
        "description": "What the work waits on, in a few words (\"PAY-2026-0429 at the bank\"). Set it only while the work needs input or waits."
      },
      "parent_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The task this one came from, when another task handed it on or asked for it."
      },
      "parent_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The task this one came from, as shown. Kept on the record."
      },
      "origin_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The first ask in a chain of tasks, kept on every task in the chain so a search by its name finds them all."
      },
      "origin_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The first ask in the chain, as shown. Kept on the record."
      },
      "result": {
        "type": "string",
        "required": false,
        "description": "What came of the work, in one line, in the words of whoever did it. Finished is their word, not someone else's acceptance.",
        "validation": {
          "maxLength": 240
        }
      },
      "tries": {
        "type": "integer",
        "required": false,
        "readOnly": true,
        "description": "How many times the work itself has been tried: a send, a payment, a count. Getting ready to do it is not a try. A\ntry is not a change of state, so it is counted here.\n",
        "validation": {
          "minimum": 0
        }
      },
      "last_try": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "When the last try was and how it ended, in one kept line (\"29 Sep, 09:15: sent again; no answer yet\").",
        "validation": {
          "maxLength": 240
        }
      }
    },
    "semantics": {
      "instruction": {
        "semantic_type": "assignment.instruction",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "What was asked"
        }
      },
      "requested_by_id": {
        "semantic_type": "assignment.requested_by.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked by",
          "displayLabelField": "requested_by_name"
        }
      },
      "requested_by_name": {
        "semantic_type": "assignment.requested_by.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked by"
        }
      },
      "requested_by_kind": {
        "semantic_type": "assignment.requested_by.kind",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Kind of asker"
        }
      },
      "requested_for_id": {
        "semantic_type": "assignment.requested_for.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked for",
          "displayLabelField": "requested_for_name"
        }
      },
      "requested_for_name": {
        "semantic_type": "assignment.requested_for.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked for"
        }
      },
      "asked_of_id": {
        "semantic_type": "assignment.asked_of.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Doing it",
          "displayLabelField": "asked_of_name"
        }
      },
      "asked_of_name": {
        "semantic_type": "assignment.asked_of.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Doing it"
        }
      },
      "asked_of_kind": {
        "semantic_type": "assignment.asked_of.kind",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Kind of doer"
        }
      },
      "subject_type": {
        "semantic_type": "assignment.subject.type",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Kind of thing"
        }
      },
      "subject_id": {
        "semantic_type": "assignment.subject.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "About",
          "displayLabelField": "subject_name"
        }
      },
      "subject_name": {
        "semantic_type": "assignment.subject.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "About"
        }
      },
      "due_at": {
        "semantic_type": "assignment.due_at",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "RelativeTimestamp",
          "label": "Due"
        }
      },
      "waiting_on_type": {
        "semantic_type": "assignment.waiting_on.type",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Kind of thing waited on"
        }
      },
      "waiting_on_id": {
        "semantic_type": "assignment.waiting_on.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Waiting on",
          "displayLabelField": "waiting_on_name"
        }
      },
      "waiting_on_name": {
        "semantic_type": "assignment.waiting_on.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Waiting on"
        }
      },
      "parent_id": {
        "semantic_type": "assignment.parent.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Came from",
          "displayLabelField": "parent_name"
        }
      },
      "parent_name": {
        "semantic_type": "assignment.parent.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Came from"
        }
      },
      "origin_id": {
        "semantic_type": "assignment.origin.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "First ask",
          "displayLabelField": "origin_name"
        }
      },
      "origin_name": {
        "semantic_type": "assignment.origin.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "First ask"
        }
      },
      "result": {
        "semantic_type": "assignment.result",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Result"
        }
      },
      "tries": {
        "semantic_type": "assignment.tries",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Tries"
        }
      },
      "last_try": {
        "semantic_type": "assignment.last_try",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Last try"
        }
      }
    },
    "tokens": {},
    "dependencies": [
      "Stateful"
    ],
    "metadata": {
      "created": "2026-11-13",
      "owners": [
        "Core team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "The record's facts add no interactive control; the three fields the doer writes are labelled form inputs.",
        "screenreader": "Each fact is read with its visible label, label first on the detail page and the form (\"Doing it, Billing Agent\") and value first on a list row or a card (\"Billing Agent, Doing it\")."
      },
      "regionsUsed": [
        "list",
        "card",
        "detail",
        "form"
      ],
      "examples": [
        "Task"
      ],
      "references": [
        "HL7 FHIR R5 Task: requester (the creator of the task), owner (responsible for managing its execution), performer and for (who benefits)",
        "A2A v1.0.1: a Task is server-generated in response to a message, and a task in a terminal state cannot restart; a follow-up is a new task",
        "Linear AgentSession: tracks the lifecycle of an agent run; its creator is the human user responsible for the session",
        "OASIS WS-HumanTask 1.1: sub-tasks identify their parent task (parentTaskId)"
      ]
    },
    "objects": [
      "Task"
    ],
    "source": "traits/core/Assignment.trait.yaml"
  },
  "Auditable": {
    "name": "Auditable",
    "version": "1.4.0",
    "description": "Compliance-grade audit trail trait that captures state transitions with actor,\nreason, and timestamp metadata. Auditable observes Stateful transitions and\nrecords them as an append-only audit log suitable for compliance review,\ndebugging, and timeline rendering.\n\nAuditable defines the INTERFACE for audit data — the schema shape, parameters,\nand view extensions that match the existing implementation. Advanced compliance\nfeatures (crypto-shredding, KMS integration, tamper-proof hashing) are documented\nin R21.3 research and targeted for future enrichment.\n\nCore concepts:\n- Audit Log: append-only array of AuditEntry records\n- Transition Capture: from_state → to_state with timestamp, actor, and reason\n- Retention Policy: configurable retention period for log entries\n- Actor Tracking: optional actor_id capture for accountability, with the optional names of who\n  acted, who it acted for and who approved it (actor_name, on_behalf_of_name, approved_by_name)\n- Approval Trace: an optional pointer to the approval a change rests on and its level of yes\n  (approval_id, approval_level)\n- Task Trace: an optional pointer to the task a change was made under and the task's name\n  (task_id, task_name)\n- Grant Trace: an optional pointer to the grant a change was made under and the grant's name\n  (grant_id, grant_name)\n- Reason Enforcement: optional requirement for transition justification",
    "category": "lifecycle",
    "tags": [
      "audit",
      "compliance",
      "trail",
      "lifecycle",
      "transition",
      "accountability"
    ],
    "contexts": [
      "detail",
      "timeline"
    ],
    "viewExtensions": [
      {
        "component": "AuditTimeline",
        "context": "timeline",
        "position": "main",
        "priority": 60,
        "props": {
          "auditLogField": "audit_log",
          "maxVisible": 7,
          "showFromState": true,
          "showActorId": true,
          "showReason": true
        }
      },
      {
        "component": "AuditSummaryCard",
        "context": "detail",
        "position": "main",
        "priority": 50,
        "props": {
          "auditLogField": "audit_log",
          "lastN": 5,
          "showTransitionCount": true,
          "showLastTransitionTime": true,
          "showLastActor": true
        }
      }
    ],
    "parameters": [
      {
        "name": "retentionDays",
        "type": "number",
        "required": false,
        "description": "Number of days to retain audit log entries before archival eligibility.\nValue of 0 means indefinite retention. Does not auto-delete — serves as\na policy signal for downstream archival processes.\n",
        "default": 0,
        "validation": {
          "minimum": 0
        }
      },
      {
        "name": "requireTransitionReason",
        "type": "boolean",
        "required": false,
        "description": "When true, every state transition must include a reason string.\nEnforces accountability by preventing silent status changes.\n",
        "default": false
      },
      {
        "name": "trackActorId",
        "type": "boolean",
        "required": false,
        "description": "When true, actor_id is captured on each transition. Enables\nper-user audit trails and accountability reporting.\n",
        "default": true
      }
    ],
    "schema": {
      "audit_log": {
        "type": "AuditEntry[]",
        "required": true,
        "description": "Append-only chronological log of state transition events.\nEach entry captures the full context of a state change.\n",
        "default": [],
        "items": {
          "type": "object",
          "properties": {
            "from_state": {
              "type": "string",
              "required": false,
              "description": "State before the transition. Null for initial state assignment."
            },
            "to_state": {
              "type": "string",
              "required": true,
              "description": "State after the transition."
            },
            "transitioned_at": {
              "type": "datetime",
              "required": true,
              "description": "UTC timestamp when the transition occurred."
            },
            "actor_id": {
              "type": "string",
              "required": false,
              "requiredFromParameter": "trackActorId",
              "description": "Identifier of the person, agent or system that triggered the transition.\nRequired when trackActorId parameter is true.\n"
            },
            "actor_name": {
              "type": "string",
              "required": false,
              "description": "Who acted, as shown (\"Billing Agent\")."
            },
            "actor_kind": {
              "type": "string",
              "required": false,
              "description": "What kind of actor acted (person, agent or system), as the Actor trait names them.",
              "validation": {
                "enum": [
                  "person",
                  "agent",
                  "system"
                ]
              }
            },
            "on_behalf_of_name": {
              "type": "string",
              "required": false,
              "description": "The person or organization the actor acted for (\"Tidewater Co-op\")."
            },
            "on_behalf_of_id": {
              "type": "string",
              "required": false,
              "description": "Identifier of the person or organization the actor acted for."
            },
            "approved_by_name": {
              "type": "string",
              "required": false,
              "description": "Who approved the change, when someone did (\"Ruth Adeyemi\")."
            },
            "approved_by_id": {
              "type": "string",
              "required": false,
              "description": "Identifier of who approved the change."
            },
            "approval_id": {
              "type": "string",
              "required": false,
              "description": "Identifier of the Approval record the yes is kept in."
            },
            "approval_level": {
              "type": "string",
              "required": false,
              "description": "The level of yes, one of the levels the product declares (\"approval\")."
            },
            "task_id": {
              "type": "string",
              "required": false,
              "description": "Identifier of the Task record the change was made under."
            },
            "task_name": {
              "type": "string",
              "required": false,
              "description": "The task the change was made under, as shown (\"Get INV-2026-0155 paid\")."
            },
            "grant_id": {
              "type": "string",
              "required": false,
              "description": "Identifier of the Grant record the change was made under."
            },
            "grant_name": {
              "type": "string",
              "required": false,
              "description": "The grant the change was made under, as shown (\"Resend returned transfers\")."
            },
            "reason": {
              "type": "string",
              "required": false,
              "requiredFromParameter": "requireTransitionReason",
              "description": "Human-readable justification for the transition.\nRequired when requireTransitionReason parameter is true.\n"
            },
            "metadata": {
              "type": "Record<string, unknown>",
              "required": false,
              "description": "Arbitrary key-value pairs for domain-specific context\n(e.g., ticket_number, automation_rule).\n",
              "default": {}
            }
          }
        }
      }
    },
    "semantics": {
      "audit_log": {
        "semantic_type": "timeline.audit",
        "token_mapping": "tokenMap(audit.timeline.*)",
        "ui_hints": {
          "component": "AuditTimeline",
          "maxVisible": 7,
          "collapseWhenEmpty": true,
          "entryComponent": "AuditEntryCard"
        }
      },
      "audit_log.from_state": {
        "semantic_type": "audit.transition.from",
        "token_mapping": "tokenMap(audit.state.from)",
        "ui_hints": {
          "component": "StatusBadge",
          "emphasis": "subtle"
        }
      },
      "audit_log.to_state": {
        "semantic_type": "audit.transition.to",
        "token_mapping": "tokenMap(audit.state.to)",
        "ui_hints": {
          "component": "StatusBadge",
          "emphasis": "subtle"
        }
      },
      "audit_log.transitioned_at": {
        "semantic_type": "audit.transition.timestamp",
        "token_mapping": "tokenMap(audit.timestamp.*)",
        "ui_hints": {
          "component": "RelativeTimestamp"
        }
      },
      "audit_log.actor_id": {
        "semantic_type": "audit.transition.actor",
        "token_mapping": "tokenMap(audit.actor.*)",
        "ui_hints": {
          "component": "ActorBadge"
        }
      },
      "audit_log.reason": {
        "semantic_type": "audit.transition.reason",
        "token_mapping": "tokenMap(audit.reason.*)",
        "ui_hints": {
          "component": "TextBody"
        }
      }
    },
    "tokens": {
      "cmp.audit.timeline.connector.color": "var(--sys-border-default)",
      "cmp.audit.timeline.connector.width": "var(--space-px)",
      "cmp.audit.timeline.dot.color": "var(--sys-surface-accent)",
      "cmp.audit.timeline.dot.size": "var(--space-2)",
      "cmp.audit.entry.bg": "var(--sys-surface-raised)",
      "cmp.audit.entry.border": "var(--sys-border-default)",
      "cmp.audit.entry.radius": "var(--radius-md)",
      "cmp.audit.entry.padding": "var(--space-3)",
      "cmp.audit.entry.state.text": "var(--sys-text-strong)",
      "cmp.audit.entry.reason.text": "var(--sys-text-default)",
      "cmp.audit.entry.timestamp.text": "var(--sys-text-subtle)",
      "cmp.audit.entry.actor.text": "var(--sys-text-subtle)",
      "cmp.audit.summary.count.text": "var(--sys-text-strong)",
      "cmp.audit.summary.label.text": "var(--sys-text-subtle)"
    },
    "dependencies": [
      "Stateful"
    ],
    "metadata": {
      "created": "2026-02-28",
      "owners": [
        "Compliance team",
        "Engineering team"
      ],
      "maturity": "experimental",
      "accessibility": {
        "keyboard": "AuditTimeline entries are not interactive. Summary card expand/collapse\nis keyboard navigable via Enter/Space.\n",
        "screenreader": "AuditTimeline uses role=\"log\" with aria-label=\"Audit trail\".\nEach entry announces: transition direction (from → to), timestamp,\nactor, and reason as a single description.\nAuditSummaryCard announces total transition count and last activity.\n"
      },
      "regionsUsed": [
        "timeline",
        "detail"
      ],
      "examples": [
        "Subscription",
        "Invoice"
      ],
      "references": [
        "objects/provenance.v1.json#/references/ref-abca58b6f92b — existing timeline renderer",
        "objects/provenance.v1.json#/references/ref-c373015a9045 — StatusTransitionEvent interface (shared shape)",
        "R21.3 Canonical Audit Architecture — compliance-grade audit trail research (200+ pages)",
        "traits/lifecycle/Stateful.trait.yaml — required dependency (state transitions)"
      ]
    },
    "objects": [],
    "source": "traits/lifecycle/Auditable.trait.yaml"
  },
  "Authable": {
    "name": "Authable",
    "version": "1.1.0",
    "description": "Role-based access control extension pack grounded in the R21.2 membership pattern.\nEncodes roles, permissions, memberships, and adjacency edges for tenant-aware RBAC.",
    "category": "core",
    "tags": [
      "authorization",
      "rbac",
      "membership",
      "saas",
      "security"
    ],
    "contexts": [
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "RoleBadgeList",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "rolesField": "session_roles",
          "fallbackRoleParameter": "defaultRoleId"
        }
      },
      {
        "component": "MembershipPanel",
        "context": "detail",
        "position": "main",
        "priority": 75,
        "props": {
          "membershipsField": "membership_records",
          "hierarchyField": "role_hierarchy_edges",
          "roleField": "role_catalog",
          "permissionField": "permission_catalog"
        }
      },
      {
        "component": "RoleAssignmentForm",
        "context": "form",
        "position": "main",
        "priority": null,
        "props": {
          "availableRolesField": "role_catalog",
          "membershipField": "membership_records",
          "defaultRoleParameter": "defaultRoleId"
        }
      }
    ],
    "parameters": [
      {
        "name": "defaultRoleId",
        "type": "string",
        "required": false,
        "description": "Role identifier applied when tenants are provisioned without an explicit role (R21.2 §2.3).",
        "validation": {
          "pattern": "^[0-9a-fA-F-]{32,36}$"
        }
      },
      {
        "name": "hierarchyDepthLimit",
        "type": "number",
        "required": false,
        "description": "Maximum recursion depth when traversing role hierarchies for derived permissions.",
        "default": 5,
        "validation": {
          "minimum": 1,
          "maximum": 10
        }
      }
    ],
    "schema": {
      "role_catalog": {
        "type": "AuthzRoleDocument[]",
        "required": true,
        "description": "Canonical RBAC roles (R21.2 Part 4.2 TABLE 1).",
        "examples": [
          [
            {
              "id": "11111111-1111-4111-8111-111111111111",
              "name": "Owner",
              "description": "Full tenant access + invoice approval (R21.2 Table 1)."
            },
            {
              "id": "22222222-2222-4222-8222-222222222222",
              "name": "Approver",
              "description": "Workflow approver for compliance-sensitive documents."
            },
            {
              "id": "33333333-3333-4333-8333-333333333333",
              "name": "Editor",
              "description": "Contributor allowed to create + update documents in scope."
            }
          ]
        ],
        "default": []
      },
      "permission_catalog": {
        "type": "AuthzPermissionDocument[]",
        "required": true,
        "description": "Atomic permissions following resource:action notation (TABLE 2).",
        "default": []
      },
      "role_permissions": {
        "type": "Record<string, string[]>",
        "required": true,
        "description": "Junction map for role→permission edges (TABLE 3).",
        "default": {}
      },
      "membership_records": {
        "type": "AuthzMembershipDocument[]",
        "required": true,
        "description": "SaaS membership triple (member, organization_id, role_id) with UNIQUE constraint (TABLE 4). The member is a user (user_id) or any other actor (actor_id with actor_kind, such as an agent), exactly one of the two.",
        "default": []
      },
      "role_hierarchy_edges": {
        "type": "AuthzRoleHierarchyEdge[]",
        "required": false,
        "description": "Parent→child adjacency list for hierarchical RBAC (Part 3.1).",
        "default": []
      },
      "session_roles": {
        "type": "string[]",
        "required": false,
        "description": "Materialized roles granted within the current session/token exchange.",
        "default": []
      }
    },
    "semantics": {
      "membership_records": {
        "semantic_type": "authorization.memberships",
        "token_mapping": "tokenMap(authorization.memberships)",
        "ui_hints": {
          "component": "MembershipMatrix",
          "uniqueConstraint": "user_id|actor_id+organization_id+role_id"
        }
      },
      "role_catalog": {
        "semantic_type": "authorization.roles",
        "token_mapping": "tokenMap(authorization.roles)",
        "ui_hints": {
          "component": "RoleCatalogPanel"
        }
      },
      "permission_catalog": {
        "semantic_type": "authorization.permissions",
        "token_mapping": "tokenMap(authorization.permissions)",
        "ui_hints": {
          "component": "PermissionList"
        }
      }
    },
    "tokens": {
      "auth.roles.badge.bg": "var(--sys-surface-neutral)",
      "auth.roles.badge.text": "var(--sys-text-strong)",
      "auth.membership.card.border": "var(--sys-border-strong)",
      "auth.membership.card.bg": "var(--sys-surface-raised)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-19",
      "owners": [
        "Security team",
        "Platform team"
      ],
      "maturity": "experimental",
      "accessibility": {
        "keyboard": "RoleAssignmentForm keeps add/remove buttons in reading order.",
        "screenreader": "MembershipPanel announces organization, role, and permission counts per entry."
      },
      "regionsUsed": [
        "list",
        "detail",
        "form"
      ],
      "examples": [
        "User",
        "Organization"
      ],
      "references": [
        "R21.2 Canonical Data Models for Authorization Systems"
      ]
    },
    "objects": [
      "Agent",
      "Organization",
      "User"
    ],
    "source": "traits/core/Authable.trait.yaml"
  },
  "Billable": {
    "name": "Billable",
    "version": "2.1.0",
    "description": "Recurring billing mechanics trait that normalizes cycle tracking, payment timing,\nand period management for subscription-based entities. Billable owns the billing\nCYCLE — when payments occur, how periods progress, and what the payment state is.\n\nDISTINCT from Priceable — Priceable handles PRICING (amount, currency, models).\nBillable handles RECURRENCE (cycles, periods, payment timing, proration).\nA Subscription composes both: Priceable for \"how much\" and Billable for \"when/how\".\n\nCore concepts:\n- Billing Cycle: current_period_start → current_period_end with progress tracking\n- Payment Timing: prepaid (charge at period start) vs postpaid (charge at period end)\n- Proration: fractional billing when mid-cycle changes occur, with preview/commit\n  timing (proration_date), a charge-timing policy (prorationBehavior), and\n  billing-anchor-reset disclosure\n- Payment Status: tracks the outcome of the most recent collection attempt\n- Cycle Anchoring: fixed day-of-month for consistent renewal dates\n\nPRORATION SCOPE (trait-split gap): proration semantics live ONLY on this CORE\nfinancial/Billable trait. The saas-billing domain trait SaaSBillingBillable\n(domains/saas-billing/traits/billable.trait.yaml) does NOT expose proration, so a\nSubscription composing only SaaSBillingBillable silently CANNOT prorate. To enable\nproration for a SaaS subscription, compose financial/Billable (as the core\nSubscription object does, alias SubscriptionBilling).",
    "category": "financial",
    "tags": [
      "billing",
      "recurring",
      "financial",
      "cycle",
      "payment",
      "subscription"
    ],
    "contexts": [
      "card",
      "detail",
      "form",
      "list",
      "timeline"
    ],
    "viewExtensions": [
      {
        "component": "BillingSummaryBadge",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "amountField": "amount",
          "currencyField": "currency",
          "intervalField": "billing_interval",
          "minorUnitsParameter": "minorUnits"
        }
      },
      {
        "component": "CycleProgressCard",
        "context": "detail",
        "position": "main",
        "priority": 70,
        "props": {
          "progressField": "current_period_progress",
          "periodStartField": "current_period_start",
          "periodEndField": "current_period_end",
          "intervalField": "billing_interval"
        }
      },
      {
        "component": "PaymentTimeline",
        "context": "detail",
        "position": "main",
        "priority": 60,
        "props": {
          "lastPaymentField": "last_payment_at",
          "nextPaymentField": "next_payment_due_at",
          "paymentStatusField": "payment_status",
          "paymentMethodField": "payment_method_type",
          "amountField": "amount",
          "currencyField": "currency"
        }
      },
      {
        "component": "BillingIntervalSelector",
        "context": "form",
        "position": "main",
        "priority": 80,
        "props": {
          "intervalField": "billing_interval",
          "intervalsParameter": "billingIntervals"
        }
      },
      {
        "component": "BillingAmountInput",
        "context": "form",
        "position": "main",
        "priority": 75,
        "props": {
          "amountField": "amount",
          "currencyField": "currency",
          "minorUnitsParameter": "minorUnits"
        }
      },
      {
        "component": "PaymentEventTimeline",
        "context": "timeline",
        "position": null,
        "priority": null,
        "props": {
          "lastPaymentField": "last_payment_at",
          "nextPaymentField": "next_payment_due_at",
          "paymentStatusField": "payment_status",
          "amountField": "amount",
          "currencyField": "currency"
        }
      },
      {
        "component": "BillingCardMeta",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "amountField": "amount",
          "currencyField": "currency",
          "intervalField": "billing_interval",
          "minorUnitsParameter": "minorUnits"
        }
      }
    ],
    "parameters": [
      {
        "name": "defaultCurrency",
        "type": "string",
        "required": false,
        "description": "ISO 4217 currency code used when a value is not explicitly provided.",
        "default": "usd",
        "validation": {
          "pattern": "^[a-zA-Z]{3}$"
        }
      },
      {
        "name": "billingIntervals",
        "type": "string[]",
        "required": false,
        "description": "Allowed billing interval values that downstream objects may select.",
        "default": [
          "monthly",
          "quarterly",
          "annual"
        ]
      },
      {
        "name": "minorUnits",
        "type": "number",
        "required": false,
        "description": "Number of fractional units that constitute a single major currency unit (e.g., 100 for cents).",
        "default": 100,
        "validation": {
          "minimum": 1
        }
      },
      {
        "name": "paymentTiming",
        "type": "string",
        "required": false,
        "description": "Whether the billing entity charges at the start of the period (prepaid)\nor at the end (postpaid). Affects cycle progress interpretation and\ndunning trigger points.\n",
        "default": "prepaid",
        "validation": {
          "enum": [
            "prepaid",
            "postpaid"
          ]
        }
      },
      {
        "name": "supportProration",
        "type": "boolean",
        "required": false,
        "description": "Whether mid-cycle plan changes generate prorated charges or credits.\nWhen true, proration_amount is computed on plan upgrades/downgrades.\n",
        "default": false
      },
      {
        "name": "prorationBehavior",
        "type": "string",
        "required": false,
        "description": "Default policy for how mid-cycle plan changes are billed, mirroring Stripe's\nproration_behavior on subscription updates. Drives charge TIMING, not the\nproration math, and is only meaningful when supportProration is true:\n- create_prorations: generate prorated line items, billed on the next invoice (default)\n- always_invoice: generate prorations AND invoice them immediately\n- none: apply the change with no proration line items / no immediate adjustment\nSource: docs.stripe.com/billing/subscriptions/prorations.\n",
        "default": "create_prorations",
        "validation": {
          "enum": [
            "create_prorations",
            "always_invoice",
            "none"
          ]
        }
      },
      {
        "name": "cycleAnchorDay",
        "type": "number",
        "required": false,
        "description": "Day of the month used to anchor renewal dates. When set, all billing\nperiods align to this day regardless of subscription start date.\nValue of 0 means no anchoring (period starts from subscription creation).\n\nBILLING-ANCHOR-RESET DISCLOSURE: changing the billing interval — or otherwise\nresetting the billing cycle anchor (e.g. Stripe billing_cycle_anchor=now) — RESETS\nthe anchor and starts a new billing period immediately. This interacts with\nproration: the reset can itself trigger proration for the current period and shifts\nthe renewal date. Surface this consequence to the user BEFORE applying an interval\nchange. Source: docs.stripe.com/billing/subscriptions/prorations.\n",
        "default": 0,
        "validation": {
          "minimum": 0,
          "maximum": 31
        }
      }
    ],
    "schema": {
      "amount": {
        "type": "integer",
        "required": true,
        "description": "Recurring price expressed in minor currency units (e.g., cents).",
        "validation": {
          "minimum": 0
        }
      },
      "currency": {
        "type": "string",
        "required": true,
        "description": "ISO 4217 currency code for the billing amount.",
        "validation": {
          "pattern": "^[a-zA-Z]{3}$"
        }
      },
      "billing_interval": {
        "type": "string",
        "required": true,
        "description": "Recurrence cadence label selected from the billingIntervals parameter.",
        "validation": {
          "enumFromParameter": "billingIntervals"
        }
      },
      "payment_status": {
        "type": "string",
        "required": false,
        "description": "Outcome of the most recent collection attempt. Distinct from subscription\nlifecycle status — a subscription can be \"active\" with payment_status \"retrying\".\n",
        "validation": {
          "enum": [
            "pending",
            "succeeded",
            "failed",
            "retrying",
            "refunded"
          ]
        },
        "default": "pending"
      },
      "payment_method_type": {
        "type": "string",
        "required": false,
        "description": "Payment instrument category used for collection.",
        "validation": {
          "enum": [
            "card",
            "ach",
            "wire",
            "invoice",
            "other"
          ]
        }
      },
      "proration_amount": {
        "type": "integer",
        "required": false,
        "description": "Prorated credit or charge in minor currency units generated by a mid-cycle\nplan change. Positive values are charges; negative values are credits.\nOnly populated when the supportProration parameter is true.\n",
        "default": 0
      },
      "proration_date": {
        "type": "integer",
        "required": false,
        "description": "Unix timestamp (epoch SECONDS) at which proration is calculated. Pinned when an\nupcoming-invoice PREVIEW is requested and MUST be passed identically on commit so the\ncommitted charge equals the previewed amount. The preview is read-only and does NOT\nmutate the subscription. Stored as an integer (not a datetime) so the value round-trips\nbyte-identically between preview and commit — an ISO string normalization could shift it\nand desync the previewed vs charged amount. Only populated when supportProration is true.\nSource: docs.stripe.com/billing/subscriptions/prorations.\n",
        "validation": {
          "minimum": 0
        }
      },
      "last_payment_at": {
        "type": "datetime",
        "required": false,
        "description": "Timestamp of the most recent successful payment."
      },
      "next_payment_due_at": {
        "type": "datetime",
        "required": false,
        "description": "Timestamp when the next payment attempt is scheduled."
      },
      "current_period_start": {
        "type": "datetime",
        "required": false,
        "description": "Beginning timestamp of the active billing cycle."
      },
      "current_period_end": {
        "type": "datetime",
        "required": false,
        "description": "Ending timestamp of the active billing cycle."
      },
      "current_period_progress": {
        "type": "number",
        "required": false,
        "description": "Decimal (0.0–1.0) indicating progress through the active billing cycle.",
        "validation": {
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "semantics": {
      "amount": {
        "semantic_type": "billing.cycle.amount_minor",
        "token_mapping": "tokenMap(billing.amount.*)",
        "ui_hints": {
          "component": "CurrencyAmount",
          "currencyField": "currency",
          "minorUnitsParameter": "minorUnits"
        }
      },
      "currency": {
        "semantic_type": "billing.cycle.currency",
        "token_mapping": "tokenMap(billing.currency.*)",
        "ui_hints": {
          "component": "CurrencyCode"
        }
      },
      "billing_interval": {
        "semantic_type": "billing.cycle.interval",
        "token_mapping": "tokenMap(billing.interval.*)",
        "ui_hints": {
          "component": "BillingIntervalBadge",
          "parameterSource": "billingIntervals"
        }
      },
      "payment_status": {
        "semantic_type": "billing.cycle.payment_status",
        "token_mapping": "tokenMap(billing.payment.status.*)",
        "ui_hints": {
          "component": "PaymentStatusBadge"
        }
      },
      "payment_method_type": {
        "semantic_type": "billing.cycle.payment_method",
        "token_mapping": "tokenMap(billing.payment.method.*)",
        "ui_hints": {
          "component": "PaymentMethodIcon"
        }
      },
      "proration_amount": {
        "semantic_type": "billing.cycle.proration",
        "token_mapping": "tokenMap(billing.proration.*)",
        "ui_hints": {
          "minorUnitsParameter": "minorUnits",
          "component": "CurrencyAmount",
          "currencyField": "currency",
          "signIndicator": true
        }
      },
      "proration_date": {
        "semantic_type": "billing.cycle.proration_timestamp",
        "token_mapping": "tokenMap(billing.timestamp.proration)",
        "ui_hints": {
          "component": "Timestamp",
          "unixSeconds": true
        }
      },
      "last_payment_at": {
        "semantic_type": "billing.cycle.last_payment_at",
        "token_mapping": "tokenMap(billing.timestamp.last_payment)",
        "ui_hints": {
          "component": "RelativeTimestamp"
        }
      },
      "next_payment_due_at": {
        "semantic_type": "billing.cycle.next_payment_due_at",
        "token_mapping": "tokenMap(billing.timestamp.next_payment)",
        "ui_hints": {
          "component": "RelativeTimestamp",
          "urgencyThresholdDays": 3
        }
      },
      "current_period_start": {
        "semantic_type": "billing.cycle.period_start",
        "token_mapping": "tokenMap(billing.timestamp.period_start)",
        "ui_hints": {
          "component": "Timestamp"
        }
      },
      "current_period_end": {
        "semantic_type": "billing.cycle.period_end",
        "token_mapping": "tokenMap(billing.timestamp.period_end)",
        "ui_hints": {
          "component": "Timestamp"
        }
      },
      "current_period_progress": {
        "semantic_type": "billing.cycle.period_progress",
        "token_mapping": "tokenMap(billing.cycle.progress)",
        "ui_hints": {
          "component": "CycleProgressBar"
        }
      }
    },
    "tokens": {
      "cmp.billing.amount.text": "var(--sys-text-strong)",
      "cmp.billing.amount.currency": "var(--sys-text-subtle)",
      "cmp.billing.amount.interval": "var(--sys-text-subtle)",
      "cmp.billing.cycle.progress.track": "var(--sys-surface-neutral)",
      "cmp.billing.cycle.progress.fill": "var(--sys-surface-accent)",
      "cmp.billing.cycle.progress.text": "var(--sys-text-default)",
      "cmp.billing.cycle.progress.height": "var(--space-1)",
      "cmp.billing.cycle.progress.radius": "var(--radius-full)",
      "cmp.billing.payment.succeeded.bg": "var(--sys-surface-success)",
      "cmp.billing.payment.succeeded.text": "var(--sys-text-success)",
      "cmp.billing.payment.failed.bg": "var(--sys-surface-critical)",
      "cmp.billing.payment.failed.text": "var(--sys-text-critical)",
      "cmp.billing.payment.retrying.bg": "var(--sys-surface-warning)",
      "cmp.billing.payment.retrying.text": "var(--sys-text-warning)",
      "cmp.billing.payment.pending.bg": "var(--sys-surface-info)",
      "cmp.billing.payment.pending.text": "var(--sys-text-info)",
      "cmp.billing.timeline.connector": "var(--sys-border-default)",
      "cmp.billing.timeline.dot": "var(--sys-surface-accent)",
      "cmp.billing.timeline.text": "var(--sys-text-default)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-10-16",
      "updated": "2026-06-24",
      "owners": [
        "Billing team",
        "Finance team"
      ],
      "maturity": "experimental",
      "accessibility": {
        "keyboard": "BillingIntervalSelector is keyboard navigable via arrow keys.\nBillingAmountInput supports standard numeric input patterns.\n",
        "screenreader": "BillingSummaryBadge announces amount, currency, and interval as a single phrase.\nCycleProgressCard announces progress percentage and remaining days.\nPaymentStatusBadge announces payment outcome with tone-appropriate urgency.\n"
      },
      "regionsUsed": [
        "list",
        "detail",
        "form",
        "timeline",
        "card"
      ],
      "examples": [
        "Subscription",
        "Plan"
      ],
      "references": [
        "objects/provenance.v1.json#/references/ref-0d9aaa77f987 — BillableViewData, BillingSummary, PastDueAction",
        "objects/provenance.v1.json#/references/ref-374e980524b1 — CanonicalSubscription, BillingInterval, BillingAccount",
        "domains/saas-billing/traits/billable.trait.yaml — SaaS domain extension",
        "objects/core/Subscription.object.yaml — Subscription object composition",
        "objects/provenance.v1.json#/references/ref-be33a98177f7 — billing domain status tokens"
      ]
    },
    "objects": [
      "Subscription"
    ],
    "source": "traits/financial/Billable.trait.yaml"
  },
  "Cancellable": {
    "name": "Cancellable",
    "version": "1.0.0",
    "description": "Adds lifecycle-aware cancellation workflows with policy guardrails and semantic token mappings.",
    "category": "lifecycle",
    "tags": [
      "lifecycle",
      "cancellation",
      "retention",
      "workflow"
    ],
    "contexts": [
      "card",
      "detail",
      "form"
    ],
    "viewExtensions": [
      {
        "component": "CancellationSummary",
        "context": "detail",
        "position": "top",
        "priority": null,
        "props": {
          "hideWhenDefault": true,
          "cancelAtPeriodEndField": "cancel_at_period_end",
          "reasonField": "cancellation_reason",
          "codeField": "cancellation_reason_code",
          "requestedAtField": "cancellation_requested_at"
        }
      },
      {
        "component": "CancellationForm",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "reasonField": "cancellation_reason",
          "codeField": "cancellation_reason_code",
          "requireReasonParameter": "requireReason",
          "allowedReasonsParameter": "allowedReasons",
          "windowParameter": "cancellationWindowHours"
        }
      },
      {
        "component": "CancellationBadge",
        "context": "card",
        "position": "before",
        "priority": null,
        "props": {
          "field": "cancel_at_period_end",
          "hideWhenFalse": true
        }
      }
    ],
    "parameters": [
      {
        "name": "allowCancellationAfterStart",
        "type": "boolean",
        "required": false,
        "description": "Whether cancellation may occur after the entity transitions to an active state.",
        "default": true
      },
      {
        "name": "cancellationWindowHours",
        "type": "number",
        "required": false,
        "description": "Number of hours after activation where cancellation is permitted.",
        "validation": {
          "minimum": 0,
          "maximum": 720
        }
      },
      {
        "name": "requireReason",
        "type": "boolean",
        "required": false,
        "description": "Whether a structured cancellation reason must be supplied by the actor.",
        "default": false
      },
      {
        "name": "allowedReasons",
        "type": "string[]",
        "required": false,
        "description": "Allow list of valid cancellation reason codes when requireReason is true.",
        "validation": {
          "minItems": 1,
          "uniqueItems": true,
          "items": {
            "pattern": "^[a-z0-9_\\-]+$",
            "minLength": 1,
            "maxLength": 64
          }
        }
      }
    ],
    "schema": {
      "cancel_at_period_end": {
        "type": "boolean",
        "required": true,
        "description": "Whether cancellation occurs at the natural period end instead of immediately. When true the entity is in a REVERSIBLE pending-cancellation state: the schedule can be undone (set back to false) any time before period end, returning the entity to active. This is distinct from a terminal cancellation (a `terminated`/canceled subscription), which is irreversible and non-reactivatable. Mirrors Stripe's cancel_at_period_end flag (docs.stripe.com/billing/subscriptions/cancel).",
        "default": false
      },
      "cancellation_reason": {
        "type": "string",
        "required": false,
        "description": "Free-form detail describing why cancellation occurred.",
        "validation": {
          "maxLength": 160
        }
      },
      "cancellation_reason_code": {
        "type": "string",
        "required": false,
        "description": "Structured reason code chosen from the allowedReasons parameter.",
        "validation": {
          "enumFromParameter": "allowedReasons"
        }
      },
      "cancellation_requested_at": {
        "type": "datetime",
        "required": false,
        "description": "Timestamp capturing when the cancellation workflow was initiated."
      }
    },
    "semantics": {
      "cancel_at_period_end": {
        "semantic_type": "status.cancel.deferred",
        "token_mapping": "tokenMap(status.cancel.*)",
        "ui_hints": {
          "component": "CancellationToggle",
          "emphasizeWhenTrue": true
        }
      },
      "cancellation_reason": {
        "semantic_type": "status.cancel.reason",
        "token_mapping": "tokenMap(status.cancel.reason)",
        "ui_hints": {
          "component": "CancellationReason",
          "multiline": true,
          "maxLength": 160
        }
      },
      "cancellation_reason_code": {
        "semantic_type": "status.cancel.reason_code",
        "token_mapping": "tokenMap(status.cancel.code.*)",
        "ui_hints": {
          "component": "ReasonPicker",
          "parameterSource": "allowedReasons"
        }
      },
      "cancellation_requested_at": {
        "semantic_type": "status.cancel.timestamp",
        "token_mapping": "tokenMap(status.cancel.timestamp)",
        "ui_hints": {
          "component": "TimelineTimestamp"
        }
      }
    },
    "tokens": {
      "status.cancel.primary.bg": "var(--status-cancel-bg)",
      "status.cancel.primary.text": "var(--status-cancel-text)",
      "status.cancel.reason.text": "var(--text-default)",
      "status.cancel.timestamp.text": "var(--text-subtle)"
    },
    "dependencies": [
      "Stateful"
    ],
    "metadata": {
      "created": "2025-10-12",
      "owners": [
        "Lifecycle team",
        "Support team"
      ],
      "maturity": "stable",
      "accessibility": {
        "keyboard": "Supports toggling of cancellation switches.",
        "screenreader": "Announces cancellation state and reason."
      },
      "regionsUsed": [
        "detail",
        "form",
        "card"
      ],
      "examples": [
        "Subscription",
        "Reservation"
      ],
      "references": [
        "Trait Engine Spec v0.1 §2"
      ]
    },
    "objects": [
      "Subscription",
      "Task",
      "Transaction"
    ],
    "source": "traits/lifecycle/Cancellable.trait.yaml"
  },
  "Classifiable": {
    "name": "Classifiable",
    "version": "1.0.0",
    "description": "Canonical taxonomy + folksonomy trait supporting taxonomy, tag, and hybrid modes with governance metadata.",
    "category": "core",
    "tags": [
      "taxonomy",
      "tags",
      "ltree",
      "classification",
      "governance"
    ],
    "contexts": [
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "ClassificationBadge",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "mode": "{classification_mode}",
          "primaryCategoryField": "primary_category_id",
          "tagPreviewField": "tag_preview"
        }
      },
      {
        "component": "ClassificationPanel",
        "context": "detail",
        "position": "sidebar",
        "priority": 40,
        "props": {
          "categoriesField": "categories",
          "tagsField": "tags",
          "metadataField": "classification_metadata",
          "modeParameter": "classification_mode"
        }
      },
      {
        "component": "ClassificationEditor",
        "context": "form",
        "position": "main",
        "priority": null,
        "props": {
          "modeParameter": "classification_mode",
          "tagPolicyParameter": "tag_policy",
          "maxTagsParameter": "max_tags"
        }
      }
    ],
    "parameters": [
      {
        "name": "classification_mode",
        "type": "enum",
        "required": true,
        "enum": [
          "taxonomy",
          "tag",
          "hybrid"
        ],
        "default": "hybrid",
        "description": "taxonomy = hierarchical only, tag = folksonomy only, hybrid = WordPress three-table pattern.\n"
      },
      {
        "name": "hierarchy_storage_model",
        "type": "enum",
        "required": false,
        "enum": [
          "adjacency_list",
          "materialized_path",
          "closure_table"
        ],
        "default": "materialized_path",
        "description": "Storage pattern for taxonomy hierarchies. materialized_path assumes ltree for <3ms subtree queries.\n"
      },
      {
        "name": "tag_policy",
        "type": "enum",
        "required": false,
        "enum": [
          "locked",
          "moderated",
          "open"
        ],
        "default": "moderated",
        "description": "Controls whether tags are curated only (locked), require moderation, or are open to user generation.\n"
      },
      {
        "name": "max_tags",
        "type": "number",
        "required": false,
        "default": 10,
        "description": "Maximum number of canonical tags per object.",
        "validation": {
          "minimum": 1,
          "maximum": 50
        }
      },
      {
        "name": "require_primary_category",
        "type": "boolean",
        "required": false,
        "default": false,
        "description": "Require at least one primary taxonomy category."
      }
    ],
    "schema": {
      "classification_metadata": {
        "type": "ClassificationMetadata",
        "required": true,
        "description": "Operational metadata describing mode, storage model, governance rules, and audit timestamps.\n"
      },
      "categories": {
        "type": "CategoryNode[]",
        "required": false,
        "default": [],
        "description": "Ordered taxonomy nodes scoped to the object."
      },
      "primary_category_id": {
        "type": "string",
        "required": false,
        "description": "Identifier of the canonical taxonomy node."
      },
      "primary_category_path": {
        "type": "string",
        "required": false,
        "description": "Human-readable breadcrumb path (Electronics > Mobile > Android)."
      },
      "tags": {
        "type": "Tag[]",
        "required": false,
        "default": [],
        "description": "Canonical tag collection after synonym collapse."
      },
      "tag_count": {
        "type": "number",
        "required": false,
        "default": 0,
        "description": "Number of canonical tags assigned to the object."
      },
      "tag_preview": {
        "type": "string",
        "required": false,
        "description": "Denormalized comma-delimited preview for list renders."
      }
    },
    "semantics": {
      "classification_metadata": {
        "semantic_type": "classification.metadata",
        "token_mapping": "tokenMap(classification.metadata)",
        "ui_hints": {
          "component": "ClassificationDiagnostics"
        }
      },
      "categories": {
        "semantic_type": "classification.categories",
        "token_mapping": "tokenMap(classification.categories.*)",
        "ui_hints": {
          "component": "CategoryTree"
        }
      },
      "tags": {
        "semantic_type": "classification.tags",
        "token_mapping": "tokenMap(classification.tags.*)",
        "ui_hints": {
          "component": "TagTokenCloud",
          "policyParameter": "tag_policy"
        }
      },
      "primary_category_id": {
        "semantic_type": "classification.primary",
        "token_mapping": "tokenMap(classification.primary)",
        "ui_hints": {
          "component": "CategoryBreadcrumb"
        }
      }
    },
    "tokens": {
      "classification": {
        "category": {
          "badge": {
            "bg": "var(--sys-surface-raised)",
            "border": "var(--sys-border-strong)"
          }
        },
        "tag": {
          "chip": {
            "bg": "var(--sys-surface-muted)",
            "text": "var(--sys-text-strong)"
          }
        }
      }
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-18",
      "updated": "2025-11-18",
      "owners": [
        "Core team",
        "Taxonomy team"
      ],
      "maturity": "draft",
      "references": [
        "R21.4_Deep-Dive-Implementation-Research-for-the-Classifiable-Core-Trait.md",
        "Core_Traits_Specification_Draft.md"
      ],
      "regionsUsed": [
        "list",
        "detail",
        "form"
      ]
    },
    "objects": [
      "Article",
      "Media",
      "Product"
    ],
    "source": "traits/core/Classifiable.trait.yaml"
  },
  "Closeout": {
    "name": "Closeout",
    "version": "1.0.0",
    "description": "The record of what became of the work after something ended: what ended, how and when, who it was for, what the\nrecord covers and where it stands now. It also keeps when your product stops waiting for answers, until when access\nalready given may still work, and the receipt your product sent, each as your product reports it. The Closure object,\nthe third part of the Grant story, composes this trait for a grant that was given and then ended; a team's own record of\na revocation or an offboarding can compose it too.\n\nWho was told, what each answered and what became of each piece of work are not fields of this trait. They are the\nrecord's history, through Stateful: each line names who reported it, and a line that reports without moving the\nrecord's state keeps that state. The state is the record's own lifecycle.\n\nA reference to what ended, or to who it was for, is an id and a kept name, so it still reads after that record is\ngone. Every field is written by your product when it reports, so a form reads them as facts and edits none. An\ninstant is shown in UTC, labelled so.\n\nOODS Foundry models and shows this record. It does not close anything, tell anyone, stop a token, send a receipt or\nwork out whether everything stopped. Only a report should move the record, and that rule is your product's to keep:\nOODS Foundry does not check who moves it, and on an object with a form its status can be changed there.",
    "category": "core",
    "tags": [
      "closeout-record",
      "after-the-end",
      "reported-outcome",
      "kept-receipt"
    ],
    "contexts": [
      "card",
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "LabelCell",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "field": "closes_id",
          "description": "What ended",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "LabelCell",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "field": "for_id",
          "description": "For",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "LabelCell",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "field": "closes_id",
          "description": "What ended",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "LabelCell",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "field": "for_id",
          "description": "For",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 90,
        "props": {
          "field": "closes_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 89,
        "props": {
          "field": "closes_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 88,
        "props": {
          "field": "ended_how",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 87,
        "props": {
          "field": "ended_at",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 86,
        "props": {
          "field": "for_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 85,
        "props": {
          "field": "for_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 84,
        "props": {
          "field": "scope",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 83,
        "props": {
          "field": "summary",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 82,
        "props": {
          "field": "deadline_at",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 81,
        "props": {
          "field": "still_works_until",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 80,
        "props": {
          "field": "still_works_note",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 79,
        "props": {
          "field": "receipt_sent_at",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 78,
        "props": {
          "field": "receipt_sent_to_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 77,
        "props": {
          "field": "receipt_channel",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 90,
        "props": {
          "field": "closes_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 89,
        "props": {
          "field": "closes_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 88,
        "props": {
          "field": "ended_how",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 87,
        "props": {
          "field": "ended_at",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 86,
        "props": {
          "field": "for_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 85,
        "props": {
          "field": "for_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 84,
        "props": {
          "field": "scope",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 83,
        "props": {
          "field": "summary",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 82,
        "props": {
          "field": "deadline_at",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 81,
        "props": {
          "field": "still_works_until",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 80,
        "props": {
          "field": "still_works_note",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 79,
        "props": {
          "field": "receipt_sent_at",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 78,
        "props": {
          "field": "receipt_sent_to_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 77,
        "props": {
          "field": "receipt_channel",
          "data-oods-omit-empty": true
        }
      }
    ],
    "parameters": [],
    "schema": {
      "closes_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What ended, by the id your product knows it by: for a closure, the grant."
      },
      "closes_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What ended, as shown (\"Northwind customer replies\"). Kept on the record."
      },
      "ended_how": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "How it ended: the ended record's state as people read it (\"Revoked\", \"Replaced\", \"Expired\").",
        "validation": {
          "maxLength": 64
        }
      },
      "ended_at": {
        "type": "datetime",
        "required": false,
        "readOnly": true,
        "description": "The instant it ended, as the ended record keeps it.",
        "validation": {
          "format": "date-time"
        }
      },
      "for_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who it was for, by the id your product knows them by: the person or organization the ended record was for."
      },
      "for_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who it was for, as shown (\"Northwind Traders\"). Kept on the record."
      },
      "scope": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What this record covers, in words: the systems and the work its reports speak for (\"What the support desk controls\").",
        "validation": {
          "maxLength": 240
        }
      },
      "summary": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Where it stands now, in one line your product writes with each report.",
        "validation": {
          "maxLength": 240
        }
      },
      "deadline_at": {
        "type": "datetime",
        "required": false,
        "readOnly": true,
        "description": "When your product stops waiting for answers. A line saying it passed with no answer reports only that nothing is known.",
        "validation": {
          "format": "date-time"
        }
      },
      "still_works_until": {
        "type": "datetime",
        "required": false,
        "readOnly": true,
        "description": "Until when access already given may still work, as reported.",
        "validation": {
          "format": "date-time"
        }
      },
      "still_works_note": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What access already given may still work, and until when, in words (\"Not known: the booking service has not said\").",
        "validation": {
          "maxLength": 240
        }
      },
      "receipt_sent_at": {
        "type": "datetime",
        "required": false,
        "readOnly": true,
        "description": "When your product sent the receipt, outside this page.",
        "validation": {
          "format": "date-time"
        }
      },
      "receipt_sent_to_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who the receipt was sent to, as shown. Kept on the record."
      },
      "receipt_channel": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "How the receipt was sent (\"Email\").",
        "validation": {
          "maxLength": 64
        }
      }
    },
    "semantics": {
      "closes_id": {
        "semantic_type": "closeout.closes_id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "What ended",
          "displayLabelField": "closes_name"
        }
      },
      "closes_name": {
        "semantic_type": "closeout.closes_name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "What ended"
        }
      },
      "ended_how": {
        "semantic_type": "closeout.ended_how",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "How it ended"
        }
      },
      "ended_at": {
        "semantic_type": "closeout.ended_at",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "RelativeTimestamp",
          "label": "When it ended"
        }
      },
      "for_id": {
        "semantic_type": "closeout.for_id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "For",
          "displayLabelField": "for_name"
        }
      },
      "for_name": {
        "semantic_type": "closeout.for_name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "For"
        }
      },
      "scope": {
        "semantic_type": "closeout.scope",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "This record covers"
        }
      },
      "summary": {
        "semantic_type": "closeout.summary",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Where it stands"
        }
      },
      "deadline_at": {
        "semantic_type": "closeout.deadline_at",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "RelativeTimestamp",
          "label": "Waits for answers until"
        }
      },
      "still_works_until": {
        "semantic_type": "closeout.still_works_until",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "RelativeTimestamp",
          "label": "May still work until"
        }
      },
      "still_works_note": {
        "semantic_type": "closeout.still_works_note",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "What may still work"
        }
      },
      "receipt_sent_at": {
        "semantic_type": "closeout.receipt_sent_at",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "RelativeTimestamp",
          "label": "Receipt sent"
        }
      },
      "receipt_sent_to_name": {
        "semantic_type": "closeout.receipt_sent_to_name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Receipt sent to"
        }
      },
      "receipt_channel": {
        "semantic_type": "closeout.receipt_channel",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Receipt sent by"
        }
      }
    },
    "tokens": {},
    "dependencies": [
      "Stateful"
    ],
    "metadata": {
      "created": "2026-11-17",
      "owners": [
        "Core team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "The record's facts add no interactive control.",
        "screenreader": "Each fact is read with its visible label, label first on the detail page and the form (\"For, Northwind Traders\") and value first on a list row or a card (\"Northwind Traders, For\")."
      },
      "regionsUsed": [
        "list",
        "card",
        "detail",
        "form"
      ],
      "examples": [
        "Closure"
      ],
      "references": [
        "draft-watts-oauth-agent-revocation-closure-04 (individual Internet-Draft, 16 Nov 2026): a closure receipt in six states, where PARTIAL, FAILED and UNKNOWN MUST NOT be interpreted as CLOSED",
        "draft-hardt-oauth-aauth-protocol-11, section 11.12.3: a PS MAY report the outcome of a revocation the person initiated to that person, per recipient",
        "draft-abak-agent-control-delivery-evidence-02 (individual Internet-Draft, 11 Oct 2026): one result per instruction and target, APPLIED, REFUSED, NO_EFFECT or UNKNOWN, and work already in flight"
      ]
    },
    "objects": [
      "Closure"
    ],
    "source": "traits/core/Closeout.trait.yaml"
  },
  "Colorized": {
    "name": "Colorized",
    "version": "2.0.0",
    "description": "Maps lifecycle states to semantic color tokens for consistent status theming across the\ndesign system. Colorized is the visual bridge between the Stateful trait's data model and\nthe OODS token system's three-tier architecture (ref → theme → system → component).\n\nEvery object that composes Stateful should also compose Colorized so that status values\nresolve to a deterministic set of surface, border, text, and icon tokens. The trait\nencodes WCAG contrast enforcement, color-blind safety via redundant icon+text cues,\nand theme-aware OKLCH token resolution — ensuring status communication never relies\non color alone.",
    "category": "visual",
    "tags": [
      "color",
      "semantic",
      "status",
      "theming",
      "accessibility",
      "oklch",
      "tokens"
    ],
    "contexts": [
      "card",
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "ColorSwatch",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "field": "color_state",
          "size": "sm"
        }
      },
      {
        "component": "StatusColorLegend",
        "context": "detail",
        "position": "top",
        "priority": null,
        "props": {
          "parameter": "colorStates",
          "badgeField": "color_state",
          "showTokenReferences": true
        }
      },
      {
        "component": "ColorStatePicker",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "parameter": "colorStates",
          "field": "color_state"
        }
      },
      {
        "component": "ColorizedBadge",
        "context": "card",
        "position": "before",
        "priority": null,
        "props": {
          "field": "color_state",
          "tone": "status",
          "showIcon": true
        }
      }
    ],
    "parameters": [
      {
        "name": "colorStates",
        "type": "string[]",
        "required": true,
        "description": "Semantic tone keys that define the palette of status colors available to this object.\nEach key maps to a --cmp-status-{tone}-{surface|border|text|icon} token set.\nMust be a subset of the canonical tones defined in the status token layer.\n",
        "default": [
          "neutral",
          "info",
          "success",
          "warning",
          "critical"
        ],
        "validation": {
          "items": {
            "enum": [
              "neutral",
              "info",
              "accent",
              "success",
              "warning",
              "critical"
            ]
          }
        }
      },
      {
        "name": "contrastLevel",
        "type": "string",
        "required": false,
        "description": "WCAG contrast compliance target for all color pairings produced by this trait.\nAA requires 4.5:1 for normal text and 3:1 for large text / UI components.\nAAA requires 7:1 for normal text and 4.5:1 for large text.\nEnforced at build time by pnpm tokens:guardrails (OKLCH delta-L >= 10, delta-C <= 0.04).\n",
        "default": "AA",
        "validation": {
          "enum": [
            "AA",
            "AAA"
          ]
        }
      },
      {
        "name": "colorMode",
        "type": "string",
        "required": false,
        "description": "Controls how color_state values resolve to tokens.\n- semantic: Tones map to the system status token layer (--sys-status-{tone}-*).\n  This is the default and recommended mode for most objects.\n- custom: Tones map to object-specific component tokens (--cmp-{object}-status-{tone}-*).\n  Use when an object needs domain-specific color semantics (e.g., billing severity).\n",
        "default": "semantic",
        "validation": {
          "enum": [
            "semantic",
            "custom"
          ]
        }
      },
      {
        "name": "fallbackTone",
        "type": "string",
        "required": false,
        "description": "Tone applied when a status value cannot be resolved to a known color state.\nPrevents rendering blank or unstyled badges when status data is missing or unknown.\n",
        "default": "neutral",
        "validation": {
          "enum": [
            "neutral",
            "info",
            "accent",
            "success",
            "warning",
            "critical"
          ]
        }
      }
    ],
    "schema": {
      "color_state": {
        "type": "string",
        "required": true,
        "description": "Active semantic tone key derived from the object's current Stateful status.\nResolved at runtime by the statusRegistry via tone inference from token references.\nMust be one of the values defined in the colorStates parameter.\n",
        "validation": {
          "enumFromParameter": "colorStates"
        }
      },
      "resolved_token_set": {
        "type": "object",
        "required": false,
        "computed": true,
        "description": "Materialized CSS custom property map for the active color_state. Populated at render\ntime by the statusRegistry (src/components/statusables/statusRegistry.ts).\nContains surface, border, text, and optional icon token references.\n",
        "properties": {
          "surface": {
            "type": "string",
            "description": "Background token, e.g. var(--cmp-status-success-surface)"
          },
          "border": {
            "type": "string",
            "description": "Border token, e.g. var(--cmp-status-success-border)"
          },
          "text": {
            "type": "string",
            "description": "Foreground text token, e.g. var(--cmp-status-success-text)"
          },
          "icon": {
            "type": "string",
            "description": "Optional icon color token, e.g. var(--cmp-status-success-icon)"
          }
        }
      },
      "accessibility_label": {
        "type": "string",
        "required": false,
        "computed": true,
        "description": "Human-readable status label announced by screen readers. Generated from the\ncolor_state value via toLabel() (e.g., \"past_due\" → \"Past Due\"). Ensures status\nmeaning is communicated without reliance on color perception.\n"
      }
    },
    "semantics": {
      "color_state": {
        "semantic_type": "status.visual",
        "token_mapping": "tokenMap(status.state.*)",
        "ui_hints": {
          "component": "ColorTokenBadge",
          "parameterSource": "colorStates"
        }
      },
      "resolved_token_set": {
        "semantic_type": "status.visual.tokens",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "internal",
          "description": "Consumed by StatusBadge and ColorizedBadge at render time."
        }
      }
    },
    "tokens": {
      "status.state.badge.radius": "var(--radius-md)",
      "status.state.badge.gap": "var(--space-1)",
      "status.state.badge.icon.size": "var(--size-2)",
      "cmp-status-neutral-surface": "var(--sys-status-neutral-surface)",
      "cmp-status-neutral-border": "var(--sys-status-neutral-border)",
      "cmp-status-neutral-text": "var(--sys-status-neutral-text)",
      "cmp-status-neutral-icon": "var(--sys-status-neutral-icon)",
      "cmp-status-info-surface": "var(--sys-status-info-surface)",
      "cmp-status-info-border": "var(--sys-status-info-border)",
      "cmp-status-info-text": "var(--sys-status-info-text)",
      "cmp-status-info-icon": "var(--sys-status-info-icon)",
      "cmp-status-accent-surface": "var(--sys-status-accent-surface)",
      "cmp-status-accent-border": "var(--sys-status-accent-border)",
      "cmp-status-accent-text": "var(--sys-status-accent-text)",
      "cmp-status-accent-icon": "var(--sys-status-accent-icon)",
      "cmp-status-success-surface": "var(--sys-status-success-surface)",
      "cmp-status-success-border": "var(--sys-status-success-border)",
      "cmp-status-success-text": "var(--sys-status-success-text)",
      "cmp-status-success-icon": "var(--sys-status-success-icon)",
      "cmp-status-warning-surface": "var(--sys-status-warning-surface)",
      "cmp-status-warning-border": "var(--sys-status-warning-border)",
      "cmp-status-warning-text": "var(--sys-status-warning-text)",
      "cmp-status-warning-icon": "var(--sys-status-warning-icon)",
      "cmp-status-critical-surface": "var(--sys-status-critical-surface)",
      "cmp-status-critical-border": "var(--sys-status-critical-border)",
      "cmp-status-critical-text": "var(--sys-status-critical-text)",
      "cmp-status-critical-icon": "var(--sys-status-critical-icon)",
      "cmp-banner-background": "var(--sys-surface-neutral)",
      "cmp-banner-border": "var(--sys-border-neutral)",
      "cmp-banner-text": "var(--sys-text-neutral)"
    },
    "dependencies": [
      "Stateful"
    ],
    "metadata": {
      "created": "2025-10-12",
      "updated": "2026-02-28",
      "owners": [
        "Design team",
        "Engineering team"
      ],
      "maturity": "stable",
      "accessibility": {
        "keyboard": "n/a — Colorized is a visual presentation trait with no interactive elements.",
        "screenreader": "StatusBadge announces the accessibility_label (human-readable status) and tone.\nColor is never the sole channel for status information.\n",
        "colorBlind": "All status badges MUST include both an icon and text label alongside the color indicator.\nThis icon+text redundancy requirement ensures that deuteranopia, protanopia, and\ntritanopia users can distinguish statuses without relying on hue perception.\nThe fallbackTone parameter provides a safe default when tone inference fails.\n",
        "contrastEnforcement": "WCAG compliance is enforced at two levels:\n  1. Build-time: pnpm tokens:guardrails checks OKLCH delta-L >= 10 and delta-C <= 0.04\n     for all interactive state transitions (hover, focus, active).\n  2. Design-time: All text-on-surface pairings in the status token layer meet the\n     contrast ratio specified by the contrastLevel parameter (4.5:1 for AA, 7:1 for AAA).\nDark theme tokens (themes/dark/status.json) use direct OKLCH values tuned to maintain\nthese ratios against dark surfaces.\n"
      },
      "regionsUsed": [
        "list",
        "detail",
        "form",
        "card"
      ],
      "examples": [
        "Incident",
        "Release",
        "Subscription",
        "Invoice"
      ],
      "stateToToneMapping": {
        "description": "Canonical mapping from domain status strings to semantic tones, as implemented\nin statusRegistry.ts TOKEN_TONE_ALIASES. Objects may define additional aliases\nin their domain-specific status-map JSON files.\n",
        "mappings": [
          {
            "tone": "info",
            "aliases": [
              "info",
              "informational",
              "pending"
            ]
          },
          {
            "tone": "accent",
            "aliases": [
              "accent",
              "highlight"
            ]
          },
          {
            "tone": "success",
            "aliases": [
              "positive",
              "success",
              "ok",
              "active"
            ]
          },
          {
            "tone": "warning",
            "aliases": [
              "warning",
              "caution"
            ]
          },
          {
            "tone": "critical",
            "aliases": [
              "danger",
              "critical",
              "error",
              "negative",
              "terminated"
            ]
          },
          {
            "tone": "neutral",
            "aliases": [
              "neutral"
            ]
          }
        ]
      },
      "references": [
        "Trait Engine Spec v0.1 section 2",
        "WCAG 2.1 Success Criterion 1.4.1 — Use of Color",
        "WCAG 2.1 Success Criterion 1.4.3 — Contrast (Minimum)",
        "WCAG 2.1 Success Criterion 1.4.11 — Non-text Contrast",
        "objects/provenance.v1.json#/references/ref-ca663a7c5731 — runtime tone resolution",
        "objects/provenance.v1.json#/references/ref-a6f66bd53aac — system status tokens",
        "objects/provenance.v1.json#/references/ref-559f1f5ebb77 — dark theme OKLCH values",
        "objects/provenance.v1.json#/references/ref-be33a98177f7 — domain status mapping example"
      ]
    },
    "objects": [],
    "source": "traits/visual/Colorized.trait.yaml"
  },
  "Communicable": {
    "name": "Communicable",
    "version": "1.0.0",
    "description": "Canonical communication trait that unifies multi-channel delivery, template governance,\ndelivery policies, and threaded conversations derived from R20.1/R20.6 research. Provides\norchestration-ready schemas for channels, messages, policies, and conversations with\nPreferenceable/Authable/Classifiable integration points.",
    "category": "communication",
    "tags": [
      "notification",
      "messaging",
      "template",
      "delivery",
      "conversation"
    ],
    "contexts": [
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "MessageStatusBadge",
        "context": "list",
        "position": "before",
        "priority": 90,
        "props": {
          "statusesField": "message_statuses"
        }
      },
      {
        "component": "CommunicationDetailPanel",
        "context": "detail",
        "position": "main",
        "priority": 80,
        "props": {
          "channelsField": "channel_catalog",
          "templatesField": "template_catalog",
          "policiesField": "delivery_policies",
          "conversationsField": "conversations"
        }
      },
      {
        "component": "TemplatePicker",
        "context": "form",
        "position": "main",
        "priority": null,
        "props": {
          "templatesField": "template_catalog",
          "channelsField": "channel_catalog"
        }
      }
    ],
    "parameters": [
      {
        "name": "channelTypes",
        "type": "string[]",
        "required": false,
        "default": [
          "email",
          "sms",
          "push",
          "in_app",
          "webhook"
        ],
        "description": "Channels enabled for the tenant (R20.1 Part 2.1 multi-channel taxonomy)."
      },
      {
        "name": "supportConversations",
        "type": "boolean",
        "required": false,
        "default": true,
        "description": "Toggle for threaded conversations in addition to standalone messages."
      }
    ],
    "schema": {
      "channel_catalog": {
        "type": "Channel[]",
        "required": true,
        "description": "Provider configuration for each channel (SMTP/Twilio/FCM/Webhook).",
        "examples": [
          [
            {
              "id": "44444444-dddd-4ddd-8ddd-dddddddddddd",
              "name": "Primary Email (SMTP)",
              "type": "email"
            },
            {
              "id": "55555555-eeee-4eee-8eee-eeeeeeeeeeee",
              "name": "Twilio SMS",
              "type": "sms"
            },
            {
              "id": "66666666-ffff-4fff-8fff-ffffffffffff",
              "name": "FCM Push",
              "type": "push"
            },
            {
              "id": "77777777-0000-4000-8000-000000000000",
              "name": "Realtime In-App",
              "type": "in_app"
            }
          ]
        ],
        "default": []
      },
      "template_catalog": {
        "type": "Template[]",
        "required": true,
        "description": "Localized template definitions with declared variables per R20.1 Part 2.3.",
        "examples": [
          [
            {
              "id": "88888888-1111-4111-8111-111111111111",
              "name": "Welcome Email",
              "channelType": "email",
              "subject": "Welcome to OODS Foundry, {{firstName}}!",
              "body": "Hi {{firstName}},\n\nThanks for joining {{workspaceName}}. Activate your account using {{activationLink}}.",
              "variables": [
                "firstName",
                "workspaceName",
                "activationLink"
              ],
              "locale": "en-US"
            },
            {
              "id": "99999999-2222-4222-8222-222222222222",
              "name": "Password Reset Email",
              "channelType": "email",
              "subject": "Reset your OODS Foundry password",
              "body": "Hello {{firstName}},\n\nWe received a request to reset your password. Use this code: {{resetCode}}.",
              "variables": [
                "firstName",
                "resetCode"
              ],
              "locale": "en-US"
            },
            {
              "id": "aaaaaaa1-3333-4333-8333-333333333333",
              "name": "In-App Notification",
              "channelType": "in_app",
              "subject": "New document shared with you",
              "body": "{{actorName}} shared \"{{documentName}}\" with you. Review it before {{dueDate}}.",
              "variables": [
                "actorName",
                "documentName",
                "dueDate"
              ],
              "locale": "en-US"
            }
          ]
        ],
        "default": []
      },
      "delivery_policies": {
        "type": "DeliveryPolicy[]",
        "required": true,
        "description": "Retry/throttle/quiet-hour policies (R20.1 Part 3 lifecycle).",
        "default": []
      },
      "messages": {
        "type": "Message[]",
        "required": false,
        "description": "Atomic message payloads queued for delivery (R20.6 Part 1.2 primitives).",
        "default": []
      },
      "conversations": {
        "type": "Conversation[]",
        "required": false,
        "description": "Multi-party threaded conversations with membership metadata (R20.6 Part 3.3).",
        "default": []
      },
      "message_statuses": {
        "type": "MessageStatusEntry[]",
        "required": false,
        "description": "Delivery state machine transitions (queued → sent → delivered → failed → retried → read).",
        "default": []
      }
    },
    "semantics": {
      "channel_catalog": {
        "semantic_type": "communication.channels",
        "token_mapping": "--sys-communication-accent",
        "ui_hints": {
          "component": "ChannelGrid",
          "badges": "channel_catalog[].type"
        }
      },
      "template_catalog": {
        "semantic_type": "communication.templates",
        "token_mapping": "--sys-communication-muted",
        "ui_hints": {
          "component": "TemplateDrawer",
          "variableBadge": "template_catalog[].variables"
        }
      },
      "delivery_policies": {
        "semantic_type": "communication.delivery_policy",
        "token_mapping": "--sys-communication-accent",
        "ui_hints": {
          "component": "DeliveryPolicyCapsule"
        }
      },
      "messages": {
        "semantic_type": "communication.messages",
        "token_mapping": "--sys-communication-success",
        "ui_hints": {
          "component": "MessageTimeline"
        }
      },
      "conversations": {
        "semantic_type": "communication.conversations",
        "token_mapping": "--sys-communication-accent",
        "ui_hints": {
          "component": "ConversationViewer"
        }
      }
    },
    "tokens": {
      "communication.card.bg": "var(--sys-surface-raised)",
      "communication.card.border": "var(--sys-communication-muted)",
      "communication.status.success": "var(--sys-communication-success)",
      "communication.status.error": "var(--sys-communication-error)"
    },
    "dependencies": [
      "Preferenceable",
      "Authable"
    ],
    "metadata": {
      "created": "2025-11-20",
      "owners": [
        "Notifications team"
      ],
      "maturity": "experimental",
      "accessibility": {
        "keyboard": "ChannelGrid keeps linear tab stops and roving focus for template previews.",
        "screenreader": "MessageEventTimeline announces delivery transitions with ARIA live updates per R20.6 guidance."
      },
      "regionsUsed": [
        "list",
        "detail",
        "form"
      ],
      "references": [
        "R20.1 Canonical Notification Model",
        "R20.6 Foundational Analysis of Modern Message and Communication Systems"
      ]
    },
    "objects": [
      "Organization",
      "User"
    ],
    "source": "traits/core/Communicable.trait.yaml"
  },
  "Decision": {
    "name": "Decision",
    "version": "1.1.1",
    "description": "The record of one ask to one actor and the answer it became: who asked, and for whom; who was asked; who answered,\nand for whom when a delegate or an agent answered; about exactly what, at what level of yes, and what that yes\nmeans. An approval is a decision, not a status. The Approval object composes this trait, and the importer\nproposes it for another system's table of approvals, so every field lives here and a proposal can bind what the\nsource has.\n\nThe answer itself is not a field of this trait. It is the record's own lifecycle, through Stateful: not yet asked,\nwaiting, approved, declined, and the ways a yes ends (out of date, taken back, expired, withdrawn, not needed,\nused). A refusal changes nothing on the thing, so it is kept here and not as a line in the thing's history.\n\nA reference to a person, an agent or a thing is an id and a kept name. The name is kept on the record, so it still\nreads after the person leaves or the thing is deleted, and it is shown wherever the id is. The kinds are the Actor\ntrait's three words: person, agent or system.\n\nThe level is one of the names the product declares in `levels`, in order, the way it declares a lifecycle's states;\nthe thing approved declares the same names through Approvable. The meaning is one kept line saying what this yes\nmeans and permits, in words, written by the product when it asks (\"Sign-off: you answer for this release\"): 21 CFR\n11.50 requires a signed record to show \"the meaning (such as review, approval, responsibility, or authorship)\nassociated with the signature\". Keeping that meaning alone does not establish Part 11 compliance. Your product handles signatures and verifies the signer’s identity.\n\nOODS Foundry keeps and shows this record. It does not ask anyone, check who may answer, count answers, expire an\nask or stop a change.",
    "category": "core",
    "tags": [
      "approval-record",
      "decision-record",
      "actor-reference",
      "kept-meaning"
    ],
    "contexts": [
      "card",
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "Text",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "field": "level"
        }
      },
      {
        "component": "Text",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "field": "asked_of_id"
        }
      },
      {
        "component": "Text",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "field": "level",
          "label": "Level"
        }
      },
      {
        "component": "Text",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "field": "asked_of_id",
          "label": "Asked of"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 80,
        "props": {
          "field": "subject_id"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 79,
        "props": {
          "field": "subject_name"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 78,
        "props": {
          "field": "subject_type"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 77,
        "props": {
          "field": "shown"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 76,
        "props": {
          "field": "level"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 75,
        "props": {
          "field": "meaning"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 74,
        "props": {
          "field": "requested_by_id"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 73,
        "props": {
          "field": "requested_by_name"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 72,
        "props": {
          "field": "requested_by_kind"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 71,
        "props": {
          "field": "requested_for_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 70,
        "props": {
          "field": "requested_for_name"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 69,
        "props": {
          "field": "asked_of_id"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 68,
        "props": {
          "field": "asked_of_name"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 67,
        "props": {
          "field": "answered_by_id"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 66,
        "props": {
          "field": "answered_by_name"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 65,
        "props": {
          "field": "answered_by_kind"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 64,
        "props": {
          "field": "answered_for_id"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 63,
        "props": {
          "field": "answered_for_name"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 62,
        "props": {
          "field": "asked_at"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 61,
        "props": {
          "field": "due_at"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 60,
        "props": {
          "field": "answered_at"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 59,
        "props": {
          "field": "comment"
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 80,
        "props": {
          "field": "subject_id"
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 79,
        "props": {
          "field": "subject_name"
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 78,
        "props": {
          "field": "shown"
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 77,
        "props": {
          "field": "level"
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 76,
        "props": {
          "field": "meaning"
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 75,
        "props": {
          "field": "requested_by_id"
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 74,
        "props": {
          "field": "requested_by_name"
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 73,
        "props": {
          "field": "requested_for_id"
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 72,
        "props": {
          "field": "requested_for_name"
        }
      }
    ],
    "parameters": [
      {
        "name": "levels",
        "type": "string[]",
        "required": true,
        "description": "The levels of yes the product declares, in order, each named for the kind of yes asked for, so it reads beside\nany answer (\"Sign-off, declined\"). A record's level is one of them. The thing approved declares the same list\nthrough Approvable. The defaults are four example levels taken from working systems.\n",
        "default": [
          "acknowledgement",
          "review",
          "approval",
          "sign_off"
        ]
      }
    ],
    "schema": {
      "requested_by_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who asked for the yes, by the id the product knows them by."
      },
      "requested_by_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who asked, as shown (\"Billing Agent\"). Kept on the record."
      },
      "requested_by_kind": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What kind of actor asked (person, agent or system), as the Actor trait names them.",
        "validation": {
          "enum": [
            "person",
            "agent",
            "system"
          ]
        }
      },
      "requested_for_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who the asker acted for, when an agent or a delegate asked for someone."
      },
      "requested_for_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who the asker acted for, as shown (\"Tidewater Co-op\"). Kept on the record."
      },
      "asked_of_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who was asked, by the id the product knows them by. One record is one ask to one actor."
      },
      "asked_of_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who was asked, as shown (\"Ruth Adeyemi\"). Kept on the record."
      },
      "answered_by_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who answered, when someone has. A delegate or an agent may answer for the one who was asked."
      },
      "answered_by_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who answered, as shown. Kept on the record."
      },
      "answered_by_kind": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What kind of actor answered (person, agent or system), so a rule can say which levels an agent's yes may satisfy.",
        "validation": {
          "enum": [
            "person",
            "agent",
            "system"
          ]
        }
      },
      "answered_for_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who the answer was given for, when a delegate or an agent answered for the one who was asked."
      },
      "answered_for_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who the answer was given for, as shown. Kept on the record."
      },
      "subject_type": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What kind of thing is approved (\"Transaction\", \"Article\")."
      },
      "subject_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The thing approved, by the id the product calls it by (a payment's reference, an article's slug)."
      },
      "subject_name": {
        "type": "string",
        "required": true,
        "readOnly": true,
        "description": "The thing approved, as shown. Kept on the record, so it still reads after the thing is deleted."
      },
      "shown": {
        "type": "string",
        "required": true,
        "readOnly": true,
        "description": "Exactly what the person was shown, in one line, which is what a yes approves: for a document, its version\n(\"Version 3, saved 1 Jul 2026\"); for an agent's action, the action and its particulars, with anything it must do\ndifferently this time:\n\"Resend $12,000.00 by bank transfer for INV-2026-0155, with the invoice number in the reference\".\nA comment never changes it.\n",
        "validation": {
          "maxLength": 240
        }
      },
      "level": {
        "type": "string",
        "required": true,
        "readOnly": true,
        "description": "The level of yes asked for, one of the levels the product declares.",
        "validation": {
          "enumFromParameter": "levels"
        }
      },
      "meaning": {
        "type": "string",
        "required": true,
        "readOnly": true,
        "description": "What this yes means and permits, in words, kept on the record (\"Sign-off: you answer for this release\"). The\nproduct writes it when it asks; OODS Foundry keeps it and shows it.\n",
        "validation": {
          "maxLength": 240
        }
      },
      "asked_at": {
        "type": "datetime",
        "required": false,
        "readOnly": true,
        "description": "When the person was asked. Absent while the ask is not yet theirs.",
        "validation": {
          "format": "date-time"
        }
      },
      "due_at": {
        "type": "datetime",
        "required": false,
        "readOnly": true,
        "description": "When an answer is due, when the product sets a date.",
        "validation": {
          "format": "date-time"
        }
      },
      "answered_at": {
        "type": "datetime",
        "required": false,
        "readOnly": true,
        "description": "When the answer was given. Absent while it is waiting.",
        "validation": {
          "format": "date-time"
        }
      },
      "comment": {
        "type": "string",
        "required": false,
        "description": "What the person who answered said with their answer.",
        "validation": {
          "maxLength": 500
        }
      }
    },
    "semantics": {
      "requested_by_id": {
        "semantic_type": "decision.requested_by.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked by",
          "displayLabelField": "requested_by_name"
        }
      },
      "requested_by_name": {
        "semantic_type": "decision.requested_by.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked by"
        }
      },
      "requested_by_kind": {
        "semantic_type": "decision.requested_by.kind",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Kind of asker"
        }
      },
      "requested_for_id": {
        "semantic_type": "decision.requested_for.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked for",
          "displayLabelField": "requested_for_name"
        }
      },
      "requested_for_name": {
        "semantic_type": "decision.requested_for.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked for"
        }
      },
      "asked_of_id": {
        "semantic_type": "decision.asked_of.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked of",
          "displayLabelField": "asked_of_name"
        }
      },
      "asked_of_name": {
        "semantic_type": "decision.asked_of.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked of"
        }
      },
      "answered_by_id": {
        "semantic_type": "decision.answered_by.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Answered by",
          "displayLabelField": "answered_by_name"
        }
      },
      "answered_by_name": {
        "semantic_type": "decision.answered_by.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Answered by"
        }
      },
      "answered_by_kind": {
        "semantic_type": "decision.answered_by.kind",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Kind of answerer"
        }
      },
      "answered_for_id": {
        "semantic_type": "decision.answered_for.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Answered for",
          "displayLabelField": "answered_for_name"
        }
      },
      "answered_for_name": {
        "semantic_type": "decision.answered_for.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Answered for"
        }
      },
      "subject_type": {
        "semantic_type": "decision.subject.type",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Kind of thing"
        }
      },
      "subject_id": {
        "semantic_type": "decision.subject.id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Approving",
          "displayLabelField": "subject_name"
        }
      },
      "subject_name": {
        "semantic_type": "decision.subject.name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Approving"
        }
      },
      "shown": {
        "semantic_type": "decision.shown",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "What was shown"
        }
      },
      "level": {
        "semantic_type": "decision.level",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Level",
          "enumLabels": {
            "sign_off": "Sign-off"
          }
        }
      },
      "meaning": {
        "semantic_type": "decision.meaning",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "What this yes means"
        }
      },
      "asked_at": {
        "semantic_type": "decision.asked_at",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "RelativeTimestamp",
          "label": "Asked"
        }
      },
      "due_at": {
        "semantic_type": "decision.due_at",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "RelativeTimestamp",
          "label": "Due"
        }
      },
      "answered_at": {
        "semantic_type": "decision.answered_at",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "RelativeTimestamp",
          "label": "Answered"
        }
      },
      "comment": {
        "semantic_type": "decision.comment",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Comment"
        }
      }
    },
    "tokens": {},
    "dependencies": [
      "Stateful"
    ],
    "metadata": {
      "created": "2026-11-11",
      "owners": [
        "Core team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "The record's facts add no interactive control; they render as labelled text.",
        "screenreader": "Each fact is read with its visible label (\"Level, Approval\"; \"What this yes means, Sign-off. You answer for this release\")."
      },
      "regionsUsed": [
        "list",
        "card",
        "detail",
        "form"
      ],
      "examples": [
        "Approval"
      ],
      "references": [
        "21 CFR 11.50: a signed electronic record shows the signer's name, the date and time, and the meaning associated with the signature",
        "ServiceNow sysapproval_approver: one approval record per approver, with Approving (document_id), Approver and State",
        "Coupa /api/approvals/<approval id>: approvable_type and approvable_id name the thing approved",
        "Jira Service Management ApproverDTO: approver (UserDTO) and approverDecision (approved, declined, pending)"
      ]
    },
    "objects": [
      "Approval"
    ],
    "source": "traits/core/Decision.trait.yaml"
  },
  "EncodingColor": {
    "name": "EncodingColor",
    "version": "0.2.1",
    "description": "Maps a data field to chromatic encodings using governed palettes and\nredundant channels to fulfill RDV.4 accessibility equivalence rules.",
    "category": "viz.encoding",
    "tags": [
      "viz",
      "encoding",
      "color"
    ],
    "contexts": [
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "VizEncodingBadge",
        "context": "detail",
        "position": "sidebar",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "channel": "color"
        }
      },
      {
        "component": "VizColorControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "schemeField": "viz_encoding_color_scheme",
          "channelField": "viz_encoding_color_channel",
          "redundancyField": "viz_encoding_color_redundancy",
          "contrastField": "viz_encoding_color_min_contrast"
        }
      },
      {
        "component": "VizColorLegendConfig",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent"
        }
      },
      {
        "component": "VizEncodingBadge",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "channel": "color",
          "axis": "color",
          "fieldField": "viz_encoding_color_field"
        }
      }
    ],
    "parameters": [
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment for the governed authoring recipes. Data rows remain a consumer operand."
      },
      {
        "name": "supportedSchemes",
        "type": "string[]",
        "required": true,
        "description": "Palette categories that this encoding may leverage.",
        "default": [
          "categorical",
          "sequential",
          "diverging"
        ]
      },
      {
        "name": "defaultScheme",
        "type": "string",
        "required": true,
        "description": "Palette category used when author does not specify.",
        "default": "categorical",
        "validation": {
          "enum": [
            "categorical",
            "sequential",
            "diverging"
          ]
        }
      },
      {
        "name": "redundancyMechanism",
        "type": "string",
        "required": true,
        "description": "Non-color fallback used to satisfy equivalence rules.",
        "default": "texture",
        "validation": {
          "enum": [
            "texture",
            "shape",
            "label"
          ]
        }
      },
      {
        "name": "minContrast",
        "type": "number",
        "required": false,
        "description": "Minimum contrast ratio enforced between adjacent categories.",
        "default": 4.5,
        "validation": {
          "minimum": 3,
          "maximum": 7
        }
      },
      {
        "name": "channel",
        "type": "string",
        "required": false,
        "description": "Which graphical channel color touches (fill vs stroke).",
        "default": "fill",
        "validation": {
          "enum": [
            "fill",
            "stroke"
          ]
        }
      }
    ],
    "schema": {
      "viz_encoding_color_field": {
        "type": "string",
        "required": true,
        "description": "Data field bound to chroma."
      },
      "viz_encoding_color_scheme": {
        "type": "string",
        "required": true,
        "description": "Palette category used for this encoding.",
        "defaultFromParameter": "defaultScheme",
        "validation": {
          "enumFromParameter": "supportedSchemes"
        }
      },
      "viz_encoding_color_channel": {
        "type": "string",
        "required": false,
        "description": "Graphical channel that carries color (fill or stroke).",
        "defaultFromParameter": "channel",
        "validation": {
          "enum": [
            "fill",
            "stroke"
          ]
        }
      },
      "viz_encoding_color_redundancy": {
        "type": "string",
        "required": true,
        "description": "Secondary channel used for equivalence (texture, shape, label).",
        "defaultFromParameter": "redundancyMechanism",
        "validation": {
          "enum": [
            "texture",
            "shape",
            "label"
          ]
        }
      },
      "viz_encoding_color_min_contrast": {
        "type": "number",
        "required": false,
        "description": "Minimum enforced contrast ratio between adjacent categories.",
        "defaultFromParameter": "minContrast",
        "validation": {
          "minimum": 3,
          "maximum": 7
        }
      },
      "viz_encoding_color_description": {
        "type": "string",
        "required": false,
        "description": "Natural language summary for fallback narratives.",
        "default": "Uses governed palette with redundant encodings per RDV.4."
      }
    },
    "semantics": {
      "viz_encoding_color_field": {
        "semantic_type": "viz.encoding.field",
        "token_mapping": "tokenMap(viz.encoding.field)",
        "ui_hints": {
          "component": "FieldReference"
        }
      },
      "viz_encoding_color_scheme": {
        "semantic_type": "viz.encoding.palette",
        "token_mapping": "tokenMap(viz.palette.scheme)",
        "ui_hints": {
          "component": "TextBadge"
        }
      },
      "viz_encoding_color_channel": {
        "semantic_type": "viz.encoding.channel",
        "token_mapping": "tokenMap(viz.channel)",
        "ui_hints": {
          "component": "TextBadge"
        }
      },
      "viz_encoding_color_redundancy": {
        "semantic_type": "viz.encoding.redundancy",
        "token_mapping": "tokenMap(viz.redundancy)",
        "ui_hints": {
          "component": "TextBadge"
        }
      },
      "viz_encoding_color_min_contrast": {
        "semantic_type": "viz.encoding.contrast",
        "token_mapping": "tokenMap(viz.a11y.contrast)",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "ratio"
        }
      }
    },
    "tokens": {
      "viz.encoding.color.palette.categorical": "var(--cmp-viz-color-categorical)",
      "viz.encoding.color.palette.sequential": "var(--cmp-viz-color-sequential)",
      "viz.encoding.color.palette.diverging": "var(--cmp-viz-color-diverging)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-15",
      "updated": "2026-02-28",
      "owners": [
        "Viz team",
        "Accessibility team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "rule_reference": "A11Y-R-01",
        "notes": "Requires redundant encoding + 4.5:1 contrast for adjacent hues."
      },
      "regionsUsed": [
        "detail",
        "form",
        "list"
      ],
      "references": [
        "RDV.4 Validation of Accessibility Equivalence in Trait-Driven Visualization Systems",
        "RDS.7 Trait-Driven Visualization System Specification (v0.1)"
      ]
    },
    "objects": [],
    "source": "traits/viz/encoding-color.trait.yaml"
  },
  "EncodingOpacity": {
    "name": "EncodingOpacity",
    "version": "0.1.1",
    "description": "Constant Cartesian mark opacity",
    "category": "viz.encoding",
    "tags": [
      "viz",
      "authoring"
    ],
    "contexts": [
      "detail",
      "form"
    ],
    "viewExtensions": [
      {
        "component": "VizOpacityControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent"
        }
      },
      {
        "component": "VizOpacitySummary",
        "context": "detail",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent"
        }
      }
    ],
    "parameters": [
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment; data rows are supplied by the consumer."
      }
    ],
    "schema": {},
    "semantics": {},
    "tokens": {},
    "dependencies": [],
    "metadata": {
      "regionsUsed": [
        "form",
        "detail"
      ]
    },
    "objects": [],
    "source": "traits/viz/encoding-opacity.trait.yaml"
  },
  "EncodingPositionX": {
    "name": "EncodingPositionX",
    "version": "0.2.1",
    "description": "Binds a data field to the horizontal axis. Declares allowed data types,\nscale defaults, and accessibility metadata to satisfy Normalized Viz Spec\nrequirements.",
    "category": "viz.encoding",
    "tags": [
      "viz",
      "encoding",
      "x-axis",
      "position"
    ],
    "contexts": [
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "VizAxisSummary",
        "context": "detail",
        "position": "sidebar",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "channel": "x",
          "axis": "x",
          "titleField": "viz_encoding_x_axis_title",
          "scaleField": "viz_encoding_x_scale",
          "zeroField": "viz_encoding_x_include_zero"
        }
      },
      {
        "component": "VizAxisControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "channel": "x",
          "axis": "x",
          "fieldField": "viz_encoding_x_field",
          "kindField": "viz_encoding_x_field_kind",
          "scaleField": "viz_encoding_x_scale",
          "titleField": "viz_encoding_x_axis_title",
          "zeroField": "viz_encoding_x_include_zero",
          "sortField": "viz_encoding_x_sort"
        }
      },
      {
        "component": "VizEncodingBadge",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "channel": "x",
          "axis": "x",
          "fieldField": "viz_encoding_x_field"
        }
      }
    ],
    "parameters": [
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment for the governed authoring recipes. Data rows remain a consumer operand."
      },
      {
        "name": "fieldKinds",
        "type": "string[]",
        "required": true,
        "description": "Data categories that can map to the X axis.",
        "default": [
          "nominal",
          "ordinal",
          "quantitative",
          "temporal"
        ]
      },
      {
        "name": "defaultScale",
        "type": "string",
        "required": true,
        "description": "Default scale used when none is specified by the spec author.",
        "default": "linear",
        "validation": {
          "enum": [
            "linear",
            "temporal"
          ]
        }
      },
      {
        "name": "includeZero",
        "type": "boolean",
        "required": false,
        "description": "Whether quantitative mappings force a zero baseline.",
        "default": true
      },
      {
        "name": "axisTitle",
        "type": "string",
        "required": false,
        "description": "Default title surfaced in axis + a11y description.",
        "default": "X Axis"
      },
      {
        "name": "sorting",
        "type": "string",
        "required": false,
        "description": "Default sort applied to discrete categories.",
        "default": "none",
        "validation": {
          "enum": [
            "none",
            "ascending",
            "descending"
          ]
        }
      }
    ],
    "schema": {
      "viz_encoding_x_field": {
        "type": "string",
        "required": true,
        "description": "Name of the data field bound to the X axis."
      },
      "viz_encoding_x_field_kind": {
        "type": "string",
        "required": true,
        "description": "Data classification used for heuristics and validation.",
        "validation": {
          "enumFromParameter": "fieldKinds"
        }
      },
      "viz_encoding_x_scale": {
        "type": "string",
        "required": true,
        "description": "Scale identifier applied to values (linear or temporal).",
        "defaultFromParameter": "defaultScale",
        "validation": {
          "enum": [
            "linear",
            "temporal"
          ]
        }
      },
      "viz_encoding_x_include_zero": {
        "type": "boolean",
        "required": false,
        "description": "Indicates whether zero baseline enforcement is active.",
        "defaultFromParameter": "includeZero"
      },
      "viz_encoding_x_axis_title": {
        "type": "string",
        "required": false,
        "description": "Default axis title used in UI and fallback descriptions.",
        "defaultFromParameter": "axisTitle"
      },
      "viz_encoding_x_sort": {
        "type": "string",
        "required": false,
        "description": "Default sort direction for discrete axes.",
        "defaultFromParameter": "sorting",
        "validation": {
          "enum": [
            "none",
            "ascending",
            "descending"
          ]
        }
      }
    },
    "semantics": {
      "viz_encoding_x_field": {
        "semantic_type": "viz.encoding.field",
        "token_mapping": "tokenMap(viz.encoding.field)",
        "ui_hints": {
          "component": "FieldReference"
        }
      },
      "viz_encoding_x_field_kind": {
        "semantic_type": "viz.encoding.field_kind",
        "token_mapping": "tokenMap(viz.encoding.field_kind)",
        "ui_hints": {
          "component": "TextBadge"
        }
      },
      "viz_encoding_x_scale": {
        "semantic_type": "viz.encoding.scale",
        "token_mapping": "tokenMap(viz.scale.type)",
        "ui_hints": {
          "component": "TextBadge"
        }
      },
      "viz_encoding_x_axis_title": {
        "semantic_type": "viz.encoding.axis_title",
        "token_mapping": "tokenMap(viz.axis.title)",
        "ui_hints": {
          "component": "TextField"
        }
      },
      "viz_encoding_x_include_zero": {
        "semantic_type": "viz.encoding.zero_baseline",
        "token_mapping": "tokenMap(viz.scale.zero)",
        "ui_hints": {
          "component": "BooleanBadge"
        }
      }
    },
    "tokens": {
      "viz.encoding.x.axis.title": "var(--cmp-text-strong)",
      "viz.encoding.x.axis.tick": "var(--cmp-viz-axis-tick)",
      "viz.encoding.x.axis.line": "var(--cmp-viz-axis-line)"
    },
    "dependencies": [
      "ScaleLinear"
    ],
    "metadata": {
      "created": "2025-11-15",
      "updated": "2026-02-28",
      "owners": [
        "Viz team",
        "Engineering team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "rule_reference": "A11Y-R-05",
        "notes": "Provide axis titles + descriptions for assistive tech fallbacks."
      },
      "regionsUsed": [
        "detail",
        "form",
        "list"
      ],
      "allows": [
        "MarkBar",
        "MarkLine",
        "MarkPoint",
        "MarkArea"
      ],
      "references": [
        "RDS.7 Trait-Driven Visualization System Specification (v0.1)"
      ]
    },
    "objects": [],
    "source": "traits/viz/encoding-position-x.trait.yaml"
  },
  "EncodingPositionY": {
    "name": "EncodingPositionY",
    "version": "0.2.1",
    "description": "Binds a data field to the vertical axis. Provides normalization, default\nscale hints, and a11y metadata for describing quantitative measures.",
    "category": "viz.encoding",
    "tags": [
      "viz",
      "encoding",
      "y-axis",
      "position"
    ],
    "contexts": [
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "VizAxisSummary",
        "context": "detail",
        "position": "sidebar",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "channel": "y",
          "axis": "y",
          "titleField": "viz_encoding_y_axis_title",
          "scaleField": "viz_encoding_y_scale",
          "zeroField": "viz_encoding_y_include_zero"
        }
      },
      {
        "component": "VizAxisControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "channel": "y",
          "axis": "y",
          "fieldField": "viz_encoding_y_field",
          "kindField": "viz_encoding_y_field_kind",
          "scaleField": "viz_encoding_y_scale",
          "titleField": "viz_encoding_y_axis_title",
          "zeroField": "viz_encoding_y_include_zero",
          "aggregateField": "viz_encoding_y_aggregate"
        }
      },
      {
        "component": "VizEncodingBadge",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "channel": "y",
          "axis": "y",
          "fieldField": "viz_encoding_y_field"
        }
      }
    ],
    "parameters": [
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment for the governed authoring recipes. Data rows remain a consumer operand."
      },
      {
        "name": "fieldKinds",
        "type": "string[]",
        "required": true,
        "description": "Data categories that can map to the Y axis.",
        "default": [
          "quantitative",
          "temporal",
          "ordinal"
        ]
      },
      {
        "name": "defaultScale",
        "type": "string",
        "required": true,
        "description": "Default scale used when not specified explicitly.",
        "default": "linear",
        "validation": {
          "enum": [
            "linear",
            "temporal"
          ]
        }
      },
      {
        "name": "includeZero",
        "type": "boolean",
        "required": false,
        "description": "Whether to enforce zero baseline for quantitative data.",
        "default": true
      },
      {
        "name": "axisTitle",
        "type": "string",
        "required": false,
        "description": "Default title surfaced in UI and fallback descriptions.",
        "default": "Y Axis"
      },
      {
        "name": "aggregate",
        "type": "string",
        "required": false,
        "description": "Default aggregation applied when spec omits one.",
        "default": "sum",
        "validation": {
          "enum": [
            "sum",
            "mean",
            "median",
            "count"
          ]
        }
      }
    ],
    "schema": {
      "viz_encoding_y_field": {
        "type": "string",
        "required": true,
        "description": "Name of the data field bound to the Y axis."
      },
      "viz_encoding_y_field_kind": {
        "type": "string",
        "required": true,
        "description": "Data classification used for heuristics and validation.",
        "validation": {
          "enumFromParameter": "fieldKinds"
        }
      },
      "viz_encoding_y_scale": {
        "type": "string",
        "required": true,
        "description": "Scale identifier applied to the Y axis.",
        "defaultFromParameter": "defaultScale",
        "validation": {
          "enum": [
            "linear",
            "temporal"
          ]
        }
      },
      "viz_encoding_y_include_zero": {
        "type": "boolean",
        "required": false,
        "description": "Indicates whether zero baseline enforcement is active.",
        "defaultFromParameter": "includeZero"
      },
      "viz_encoding_y_axis_title": {
        "type": "string",
        "required": false,
        "description": "Default axis title used in UI and fallback descriptions.",
        "defaultFromParameter": "axisTitle"
      },
      "viz_encoding_y_aggregate": {
        "type": "string",
        "required": false,
        "description": "Aggregation strategy applied when spec omits one.",
        "defaultFromParameter": "aggregate",
        "validation": {
          "enum": [
            "sum",
            "mean",
            "median",
            "count"
          ]
        }
      }
    },
    "semantics": {
      "viz_encoding_y_field": {
        "semantic_type": "viz.encoding.field",
        "token_mapping": "tokenMap(viz.encoding.field)",
        "ui_hints": {
          "component": "FieldReference"
        }
      },
      "viz_encoding_y_field_kind": {
        "semantic_type": "viz.encoding.field_kind",
        "token_mapping": "tokenMap(viz.encoding.field_kind)",
        "ui_hints": {
          "component": "TextBadge"
        }
      },
      "viz_encoding_y_scale": {
        "semantic_type": "viz.encoding.scale",
        "token_mapping": "tokenMap(viz.scale.type)",
        "ui_hints": {
          "component": "TextBadge"
        }
      },
      "viz_encoding_y_axis_title": {
        "semantic_type": "viz.encoding.axis_title",
        "token_mapping": "tokenMap(viz.axis.title)",
        "ui_hints": {
          "component": "TextField"
        }
      },
      "viz_encoding_y_aggregate": {
        "semantic_type": "viz.encoding.aggregate",
        "token_mapping": "tokenMap(viz.aggregate)",
        "ui_hints": {
          "component": "TextBadge"
        }
      }
    },
    "tokens": {
      "viz.encoding.y.axis.title": "var(--cmp-text-strong)",
      "viz.encoding.y.axis.tick": "var(--cmp-viz-axis-tick)",
      "viz.encoding.y.axis.line": "var(--cmp-viz-axis-line)"
    },
    "dependencies": [
      "ScaleLinear"
    ],
    "metadata": {
      "created": "2025-11-15",
      "updated": "2026-02-28",
      "owners": [
        "Viz team",
        "Engineering team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "rule_reference": "A11Y-R-05",
        "notes": "Axis title doubles as descriptive label in fallback tables."
      },
      "regionsUsed": [
        "detail",
        "form",
        "list"
      ],
      "allows": [
        "MarkBar",
        "MarkLine",
        "MarkPoint",
        "MarkArea"
      ],
      "references": [
        "RDS.7 Trait-Driven Visualization System Specification (v0.1)"
      ]
    },
    "objects": [],
    "source": "traits/viz/encoding-position-y.trait.yaml"
  },
  "EncodingShape": {
    "name": "EncodingShape",
    "version": "0.1.1",
    "description": "Categorical shape encoding",
    "category": "viz.encoding",
    "tags": [
      "viz",
      "authoring"
    ],
    "contexts": [
      "form"
    ],
    "viewExtensions": [
      {
        "component": "VizShapeControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent"
        }
      },
      {
        "component": "VizShapeLegend",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent"
        }
      }
    ],
    "parameters": [
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment; data rows are supplied by the consumer."
      }
    ],
    "schema": {},
    "semantics": {},
    "tokens": {},
    "dependencies": [],
    "metadata": {
      "regionsUsed": [
        "form"
      ]
    },
    "objects": [],
    "source": "traits/viz/encoding-shape.trait.yaml"
  },
  "EncodingSize": {
    "name": "EncodingSize",
    "version": "0.2.1",
    "description": "Maps a quantitative field to glyph size (radius or area) with governed\nranges that can be validated for perceptual correctness and accessibility.",
    "category": "viz.encoding",
    "tags": [
      "viz",
      "encoding",
      "size"
    ],
    "contexts": [
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "VizSizeSummary",
        "context": "detail",
        "position": "sidebar",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "field": "viz_encoding_size_field",
          "strategyField": "viz_encoding_size_strategy",
          "minField": "viz_encoding_size_range_min",
          "maxField": "viz_encoding_size_range_max"
        }
      },
      {
        "component": "VizSizeControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "strategyField": "viz_encoding_size_strategy",
          "minField": "viz_encoding_size_range_min",
          "maxField": "viz_encoding_size_range_max",
          "minAreaField": "viz_encoding_size_min_area",
          "maxAreaField": "viz_encoding_size_max_area"
        }
      },
      {
        "component": "VizEncodingBadge",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "channel": "size",
          "axis": "size",
          "fieldField": "viz_encoding_size_field"
        }
      }
    ],
    "parameters": [
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment for the governed authoring recipes. Data rows remain a consumer operand."
      },
      {
        "name": "rangeMin",
        "type": "number",
        "required": true,
        "description": "Minimum rendered size in device-independent pixels.",
        "default": 6,
        "validation": {
          "minimum": 2,
          "maximum": 32
        }
      },
      {
        "name": "rangeMax",
        "type": "number",
        "required": true,
        "description": "Maximum rendered size in device-independent pixels.",
        "default": 36,
        "validation": {
          "minimum": 12,
          "maximum": 96
        }
      },
      {
        "name": "strategy",
        "type": "string",
        "required": true,
        "description": "Interprets values as area or radius for perceptual scaling.",
        "default": "area",
        "validation": {
          "enum": [
            "area",
            "radius"
          ]
        }
      },
      {
        "name": "minPixelArea",
        "type": "number",
        "required": false,
        "description": "Minimum accessible area to avoid disappearing glyphs.",
        "default": 36
      },
      {
        "name": "maxPixelArea",
        "type": "number",
        "required": false,
        "description": "Maximum accessible area to avoid dominating layout.",
        "default": 576
      }
    ],
    "schema": {
      "viz_encoding_size_field": {
        "type": "string",
        "required": true,
        "description": "Data field bound to glyph size."
      },
      "viz_encoding_size_strategy": {
        "type": "string",
        "required": true,
        "description": "Defines whether size is derived from area or radius.",
        "defaultFromParameter": "strategy",
        "validation": {
          "enum": [
            "area",
            "radius"
          ]
        }
      },
      "viz_encoding_size_range_min": {
        "type": "number",
        "required": true,
        "description": "Minimum rendered size in pixels.",
        "defaultFromParameter": "rangeMin"
      },
      "viz_encoding_size_range_max": {
        "type": "number",
        "required": true,
        "description": "Maximum rendered size in pixels.",
        "defaultFromParameter": "rangeMax"
      },
      "viz_encoding_size_min_area": {
        "type": "number",
        "required": false,
        "description": "Minimum accessible area to prevent underflow.",
        "defaultFromParameter": "minPixelArea"
      },
      "viz_encoding_size_max_area": {
        "type": "number",
        "required": false,
        "description": "Maximum accessible area to prevent overflow.",
        "defaultFromParameter": "maxPixelArea"
      },
      "viz_encoding_size_description": {
        "type": "string",
        "required": false,
        "description": "Narrative summary for fallback text/table output.",
        "default": "Size encodes magnitude using governed perceptual scaling."
      }
    },
    "semantics": {
      "viz_encoding_size_field": {
        "semantic_type": "viz.encoding.field",
        "token_mapping": "tokenMap(viz.encoding.field)",
        "ui_hints": {
          "component": "FieldReference"
        }
      },
      "viz_encoding_size_strategy": {
        "semantic_type": "viz.encoding.size_strategy",
        "token_mapping": "tokenMap(viz.encoding.size_strategy)",
        "ui_hints": {
          "component": "TextBadge"
        }
      },
      "viz_encoding_size_range_min": {
        "semantic_type": "viz.encoding.size_range",
        "token_mapping": "tokenMap(viz.encoding.size_range)",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "px"
        }
      },
      "viz_encoding_size_range_max": {
        "semantic_type": "viz.encoding.size_range",
        "token_mapping": "tokenMap(viz.encoding.size_range)",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "px"
        }
      },
      "viz_encoding_size_min_area": {
        "semantic_type": "viz.encoding.a11y_min",
        "token_mapping": "tokenMap(viz.a11y.min_target)",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "px^2"
        }
      }
    },
    "tokens": {
      "viz.encoding.size.range.min": "var(--cmp-viz-size-min)",
      "viz.encoding.size.range.max": "var(--cmp-viz-size-max)",
      "viz.encoding.size.stroke": "var(--cmp-viz-size-stroke)"
    },
    "dependencies": [
      "ScaleLinear"
    ],
    "metadata": {
      "created": "2025-11-15",
      "updated": "2026-02-28",
      "owners": [
        "Viz team",
        "Research team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "rule_reference": "A11Y-R-02",
        "notes": "Ensures glyphs remain perceivable within governed range."
      },
      "regionsUsed": [
        "detail",
        "form",
        "list"
      ],
      "references": [
        "RDS.7 Trait-Driven Visualization System Specification (v0.1)"
      ]
    },
    "objects": [],
    "source": "traits/viz/encoding-size.trait.yaml"
  },
  "Filterable": {
    "name": "Filterable",
    "version": "1.0.0",
    "description": "Adds multi-facet filtering to list and collection views. Filterable injects a filter panel\ninto the sidebar or header region, wires filter state to the data layer, and provides\nsemantic token mappings for consistent filter UI styling across brands.\n\nFilters are defined as an array of filter descriptors, each specifying a field, operator,\nand available values. Active filters are tracked separately for apply/clear lifecycle.\nThe trait supports both immediate-apply and batch-apply modes for UX flexibility.",
    "category": "behavioral",
    "tags": [
      "filtering",
      "facets",
      "list-behavior",
      "data-refinement"
    ],
    "contexts": [
      "detail",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "FilterPanel",
        "context": "list",
        "position": "sidebar",
        "priority": 8,
        "props": {
          "field": "filters",
          "activeField": "activeFilters",
          "modeParameter": "filterMode",
          "maxActiveParameter": "maxActiveFilters",
          "collapsibleParameter": "collapsible"
        }
      },
      {
        "component": "FilterPanel",
        "context": "detail",
        "position": "sidebar",
        "priority": 8,
        "props": {
          "field": "filters",
          "activeField": "activeFilters",
          "modeParameter": "filterMode",
          "collapsibleParameter": "collapsible"
        }
      }
    ],
    "parameters": [
      {
        "name": "filterMode",
        "type": "string",
        "required": false,
        "description": "Controls when filter changes take effect:\n- immediate: Filters apply as soon as the user changes a value.\n- batch: Filters accumulate until the user clicks an explicit \"Apply\" button.\n",
        "default": "immediate",
        "validation": {
          "enum": [
            "immediate",
            "batch"
          ]
        }
      },
      {
        "name": "maxActiveFilters",
        "type": "number",
        "required": false,
        "description": "Maximum number of simultaneous active filters. 0 means unlimited.",
        "default": 0,
        "validation": {
          "minimum": 0,
          "maximum": 50
        }
      },
      {
        "name": "showFilterCount",
        "type": "boolean",
        "required": false,
        "description": "Whether to display a badge showing the number of active filters.",
        "default": true
      },
      {
        "name": "collapsible",
        "type": "boolean",
        "required": false,
        "description": "Whether filter panel sections can be collapsed individually.",
        "default": true
      }
    ],
    "schema": {
      "filters": {
        "type": "object[]",
        "required": false,
        "description": "Array of available filter descriptors. Each entry defines a filterable dimension:\n  - field: string (the schema field to filter on)\n  - label: string (display label)\n  - type: \"select\" | \"multi-select\" | \"range\" | \"boolean\" | \"date-range\"\n  - options: array of { value, label } for select/multi-select types\n",
        "default": []
      },
      "activeFilters": {
        "type": "object[]",
        "required": false,
        "description": "Array of currently applied filter values:\n  - field: string (matches a filter descriptor field)\n  - operator: \"eq\" | \"in\" | \"range\" | \"gt\" | \"lt\" | \"between\"\n  - value: unknown (the selected filter value or values)\n",
        "default": []
      },
      "filterCount": {
        "type": "number",
        "required": true,
        "description": "Computed count of currently active filters.",
        "default": 0,
        "validation": {
          "minimum": 0
        }
      }
    },
    "semantics": {
      "filters": {
        "semantic_type": "input.filter.descriptors",
        "token_mapping": "tokenMap(filter.panel.*)",
        "ui_hints": {
          "component": "FilterPanel",
          "modeParameter": "filterMode"
        }
      },
      "activeFilters": {
        "semantic_type": "state.filter.active",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "FilterPanel",
          "description": "Drives active filter chip display and clear actions."
        }
      },
      "filterCount": {
        "semantic_type": "metric.filter.count",
        "token_mapping": "tokenMap(filter.badge.*)",
        "ui_hints": {
          "component": "MetricBadge",
          "format": "integer"
        }
      }
    },
    "tokens": {
      "filter.panel.bg": "var(--sys-surface-secondary)",
      "filter.panel.border": "var(--sys-border-default)",
      "filter.panel.header.text": "var(--sys-text-primary)",
      "filter.panel.section.divider": "var(--sys-border-subtle)",
      "filter.chip.bg": "var(--sys-surface-accent)",
      "filter.chip.text": "var(--sys-text-on-accent)",
      "filter.chip.remove.hover": "var(--sys-surface-hover)",
      "filter.badge.bg": "var(--sys-surface-accent)",
      "filter.badge.text": "var(--sys-text-on-accent)",
      "filter.apply.bg": "var(--sys-action-primary)",
      "filter.apply.text": "var(--sys-text-on-action)",
      "filter.clear.text": "var(--sys-text-subtle)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2026-03-05",
      "updated": "2026-03-06",
      "owners": [
        "Design team"
      ],
      "maturity": "stable",
      "accessibility": {
        "keyboard": "FilterPanel supports full keyboard navigation:\n- Tab to move between filter controls\n- Enter/Space to toggle selections\n- Escape to collapse an open dropdown\n- In batch mode, Tab to Apply button, Enter to submit\n",
        "screenreader": "Filter panel is announced with role=\"region\" and aria-label=\"Filters\".\nActive filter changes are announced via aria-live when filters change.\nClear-all button is announced as \"Clear all filters\".\n"
      },
      "regionsUsed": [
        "list",
        "detail"
      ],
      "examples": [
        "Product catalog filtering",
        "Invoice list filtering",
        "User management filtering"
      ],
      "references": [
        "Trait Engine Spec v0.1 section 2"
      ]
    },
    "objects": [
      "Product"
    ],
    "source": "traits/behavioral/Filterable.trait.yaml"
  },
  "Geocodable": {
    "name": "Geocodable",
    "version": "1.0.1",
    "description": "Indicates that data contains location-resolvable information that can be\nmapped to coordinates or geographic boundaries. Supports auto-detection\nof geo fields based on naming patterns and field types.",
    "category": "viz.spatial",
    "tags": [
      "viz",
      "spatial",
      "geo",
      "location",
      "map"
    ],
    "contexts": [
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "GeocodablePreview",
        "context": "detail",
        "position": "top",
        "priority": 70,
        "props": {
          "resolutionField": "geo_resolution",
          "requiresLookupField": "geo_requires_lookup",
          "detectedFieldsField": "geo_detected_fields"
        }
      },
      {
        "component": "GeoFieldMappingForm",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "latitudeField": "geo_latitude_field",
          "longitudeField": "geo_longitude_field",
          "identifierField": "geo_identifier_field",
          "autoDetectField": "geo_auto_detect_enabled"
        }
      },
      {
        "component": "GeoResolutionBadge",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "resolutionField": "geo_resolution"
        }
      }
    ],
    "parameters": [
      {
        "name": "autoDetect",
        "type": "boolean",
        "required": false,
        "description": "Enable automatic detection of geo fields based on naming patterns.",
        "default": true
      },
      {
        "name": "explicitFields",
        "type": "string[]",
        "required": false,
        "description": "Explicitly specify which fields contain geographic data.",
        "default": []
      },
      {
        "name": "minConfidence",
        "type": "number",
        "required": false,
        "description": "Minimum confidence threshold for auto-detected fields (0-1).",
        "default": 0.7,
        "validation": {
          "minimum": 0,
          "maximum": 1
        }
      }
    ],
    "schema": {
      "geo_resolution": {
        "type": "string",
        "required": true,
        "description": "Type of geographic resolution available (point, boundary, or both).",
        "default": "point",
        "validation": {
          "enum": [
            "point",
            "boundary",
            "both"
          ]
        }
      },
      "geo_requires_lookup": {
        "type": "boolean",
        "required": true,
        "description": "Whether geographic identifiers require lookup to resolve.",
        "default": false
      },
      "geo_detected_fields": {
        "type": "object[]",
        "required": false,
        "description": "Array of detected geo fields with type and confidence.",
        "default": []
      },
      "geo_latitude_field": {
        "type": "string",
        "required": false,
        "description": "Field name containing latitude values (for point resolution)."
      },
      "geo_longitude_field": {
        "type": "string",
        "required": false,
        "description": "Field name containing longitude values (for point resolution)."
      },
      "geo_identifier_field": {
        "type": "string",
        "required": false,
        "description": "Primary field name containing geographic identifiers."
      },
      "geo_identifier_type": {
        "type": "string",
        "required": false,
        "description": "Type of geographic identifier (e.g., country, state, fips)."
      },
      "geo_auto_detect_enabled": {
        "type": "boolean",
        "required": true,
        "description": "Whether auto-detection of geo fields is enabled.",
        "default": true
      }
    },
    "semantics": {
      "geo_resolution": {
        "semantic_type": "viz.spatial.resolution",
        "token_mapping": "tokenMap(viz.spatial.resolution)",
        "ui_hints": {
          "component": "GeoResolutionBadge"
        }
      },
      "geo_requires_lookup": {
        "semantic_type": "viz.spatial.lookup",
        "token_mapping": "tokenMap(viz.spatial.lookup)",
        "ui_hints": {
          "component": "BooleanIndicator",
          "label_when_true": "Requires geocoding",
          "label_when_false": "Direct coordinates"
        }
      },
      "geo_detected_fields": {
        "semantic_type": "viz.spatial.detected_fields",
        "ui_hints": {
          "component": "GeoFieldList"
        }
      },
      "geo_latitude_field": {
        "semantic_type": "viz.spatial.coordinate.lat",
        "ui_hints": {
          "component": "FieldSelector",
          "filter": "numeric"
        }
      },
      "geo_longitude_field": {
        "semantic_type": "viz.spatial.coordinate.lon",
        "ui_hints": {
          "component": "FieldSelector",
          "filter": "numeric"
        }
      },
      "geo_identifier_field": {
        "semantic_type": "viz.spatial.identifier",
        "ui_hints": {
          "component": "FieldSelector",
          "filter": "string"
        }
      },
      "geo_identifier_type": {
        "semantic_type": "viz.spatial.identifier_type",
        "ui_hints": {
          "component": "GeoIdentifierTypeSelector"
        }
      }
    },
    "tokens": {
      "viz.spatial.geocodable.icon": "var(--cmp-viz-spatial-geocodable-icon)",
      "viz.spatial.geocodable.badge.point": "var(--cmp-viz-spatial-badge-point)",
      "viz.spatial.geocodable.badge.boundary": "var(--cmp-viz-spatial-badge-boundary)",
      "viz.spatial.geocodable.badge.both": "var(--cmp-viz-spatial-badge-both)",
      "viz.spatial.geocodable.confidence.high": "var(--cmp-viz-spatial-confidence-high)",
      "viz.spatial.geocodable.confidence.medium": "var(--cmp-viz-spatial-confidence-medium)",
      "viz.spatial.geocodable.confidence.low": "var(--cmp-viz-spatial-confidence-low)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-29",
      "updated": "2026-02-28",
      "owners": [
        "Viz team",
        "Spatial team"
      ],
      "maturity": "alpha",
      "conflicts_with": [],
      "accessibility": {
        "rule_reference": "A11Y-R-04",
        "notes": "Spatial visualizations require table fallback with region/coordinate data."
      },
      "regionsUsed": [
        "detail",
        "form",
        "list"
      ],
      "examples": [
        "SalesByState",
        "StoreLocations",
        "PopulationByCountry"
      ],
      "references": [
        "Spatial module architecture (data-viz part 2)",
        "RV.03 Gap Analysis"
      ]
    },
    "objects": [],
    "source": "traits/viz/spatial/geocodable.trait.yaml"
  },
  "InteractionHighlight": {
    "name": "InteractionHighlight",
    "version": "0.2.0",
    "description": "Emphasizes hovered or selected points by adjusting a configurable visual property.",
    "category": "viz.interaction",
    "tags": [
      "viz",
      "interaction",
      "highlight"
    ],
    "contexts": [],
    "viewExtensions": [],
    "parameters": [
      {
        "name": "fields",
        "type": "string[]",
        "required": true,
        "description": "Data fields that define the highlight predicate."
      },
      {
        "name": "trigger",
        "type": "string",
        "required": false,
        "description": "Event stream that activates the highlight.",
        "default": "hover",
        "validation": {
          "enum": [
            "hover",
            "click",
            "focus"
          ]
        }
      },
      {
        "name": "property",
        "type": "string",
        "required": false,
        "description": "Visual property to adjust when the predicate is active.",
        "default": "fillOpacity"
      },
      {
        "name": "activeValue",
        "type": "number",
        "required": false,
        "description": "Value applied to highlighted marks.",
        "default": 1,
        "validation": {
          "minimum": 0,
          "maximum": 1
        }
      },
      {
        "name": "inactiveValue",
        "type": "number",
        "required": false,
        "description": "Value applied to non-highlighted marks.",
        "default": 0.35,
        "validation": {
          "minimum": 0,
          "maximum": 1
        }
      }
    ],
    "schema": {
      "viz_interaction_highlight_fields": {
        "type": "string[]",
        "required": true,
        "description": "Fields copied into the interaction predicate."
      },
      "viz_interaction_highlight_trigger": {
        "type": "string",
        "required": true,
        "description": "Event stream used for highlight activation.",
        "defaultFromParameter": "trigger",
        "validation": {
          "enum": [
            "hover",
            "click",
            "focus"
          ]
        }
      },
      "viz_interaction_highlight_property": {
        "type": "string",
        "required": true,
        "description": "Visual property that is conditionally modified.",
        "defaultFromParameter": "property"
      },
      "viz_interaction_highlight_active_value": {
        "type": "number",
        "required": true,
        "description": "Value applied when the predicate matches.",
        "defaultFromParameter": "activeValue",
        "validation": {
          "minimum": 0,
          "maximum": 1
        }
      },
      "viz_interaction_highlight_inactive_value": {
        "type": "number",
        "required": true,
        "description": "Value applied when the predicate does not match.",
        "defaultFromParameter": "inactiveValue",
        "validation": {
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "semantics": {
      "viz_interaction_highlight_fields": {
        "semantic_type": "viz.interaction.fields",
        "ui_hints": {
          "component": "ListSummary"
        }
      },
      "viz_interaction_highlight_trigger": {
        "semantic_type": "viz.interaction.trigger",
        "ui_hints": {
          "component": "Badge"
        }
      },
      "viz_interaction_highlight_property": {
        "semantic_type": "viz.interaction.property",
        "ui_hints": {
          "component": "Code"
        }
      },
      "viz_interaction_highlight_active_value": {
        "semantic_type": "viz.interaction.value_active",
        "ui_hints": {
          "component": "NumericPreview"
        }
      },
      "viz_interaction_highlight_inactive_value": {
        "semantic_type": "viz.interaction.value_inactive",
        "ui_hints": {
          "component": "NumericPreview"
        }
      }
    },
    "tokens": {
      "viz.interaction.highlight.active.opacity": "var(--cmp-viz-highlight-active-opacity)",
      "viz.interaction.highlight.inactive.opacity": "var(--cmp-viz-highlight-inactive-opacity)",
      "viz.interaction.highlight.outline": "var(--cmp-viz-highlight-outline)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-15",
      "updated": "2026-02-28",
      "owners": [
        "Viz team",
        "Accessibility team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "Highlight is activatable via keyboard focus (trigger=focus) in addition to\nhover and click. Arrow keys navigate between data points. Enter/Space\ntoggles persistent highlight on click-triggered interactions.\n",
        "screenreader": "When a mark is highlighted, the screen reader announces the datum values\nand indicates it is selected. Non-highlighted marks are announced as\n\"dimmed\" or \"inactive\" to convey the visual distinction.\n",
        "focusManagement": "Focus ring is rendered around the highlighted mark. When highlight clears,\nfocus remains on the last interacted mark.\n"
      },
      "examples": [
        "ScatterplotBrushHighlight",
        "BarChartCategoryHighlight"
      ],
      "references": [
        "RDS.7 Trait-Driven Visualization System Specification (v0.1)"
      ]
    },
    "objects": [],
    "source": "traits/viz/interaction-highlight.trait.yaml"
  },
  "InteractionTooltip": {
    "name": "InteractionTooltip",
    "version": "0.2.0",
    "description": "Shows contextual details-on-demand when focusing or hovering a specific datum.",
    "category": "viz.interaction",
    "tags": [
      "viz",
      "interaction",
      "tooltip"
    ],
    "contexts": [],
    "viewExtensions": [],
    "parameters": [
      {
        "name": "fields",
        "type": "string[]",
        "required": true,
        "description": "Ordered field list rendered inside the tooltip."
      },
      {
        "name": "trigger",
        "type": "string",
        "required": false,
        "description": "Event stream that reveals the tooltip.",
        "default": "hover",
        "validation": {
          "enum": [
            "hover",
            "focus"
          ]
        }
      },
      {
        "name": "alignment",
        "type": "string",
        "required": false,
        "description": "Preferred tooltip alignment around the data point.",
        "default": "auto",
        "validation": {
          "enum": [
            "auto",
            "top",
            "bottom",
            "left",
            "right"
          ]
        }
      }
    ],
    "schema": {
      "viz_interaction_tooltip_fields": {
        "type": "string[]",
        "required": true,
        "description": "Fields surfaced inside the tooltip."
      },
      "viz_interaction_tooltip_trigger": {
        "type": "string",
        "required": true,
        "description": "Event stream used to reveal the tooltip.",
        "defaultFromParameter": "trigger",
        "validation": {
          "enum": [
            "hover",
            "focus"
          ]
        }
      },
      "viz_interaction_tooltip_alignment": {
        "type": "string",
        "required": false,
        "description": "Preferred tooltip alignment token.",
        "defaultFromParameter": "alignment",
        "validation": {
          "enum": [
            "auto",
            "top",
            "bottom",
            "left",
            "right"
          ]
        }
      }
    },
    "semantics": {
      "viz_interaction_tooltip_fields": {
        "semantic_type": "viz.interaction.fields",
        "ui_hints": {
          "component": "ListSummary"
        }
      },
      "viz_interaction_tooltip_trigger": {
        "semantic_type": "viz.interaction.trigger",
        "ui_hints": {
          "component": "Badge"
        }
      },
      "viz_interaction_tooltip_alignment": {
        "semantic_type": "viz.interaction.tooltip.alignment",
        "ui_hints": {
          "component": "Badge"
        }
      }
    },
    "tokens": {
      "viz.interaction.tooltip.bg": "var(--cmp-viz-tooltip-bg)",
      "viz.interaction.tooltip.text": "var(--cmp-viz-tooltip-text)",
      "viz.interaction.tooltip.border": "var(--cmp-viz-tooltip-border)",
      "viz.interaction.tooltip.shadow": "var(--cmp-viz-tooltip-shadow)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-15",
      "updated": "2026-02-28",
      "owners": [
        "Viz team",
        "Accessibility team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "Tooltip is triggered on focus (not just hover) to support keyboard-only users.\nEscape dismisses the tooltip. Tooltip content is not focusable — it is read-only\nsupplementary information announced by the screen reader.\n",
        "screenreader": "Tooltip content is exposed via aria-describedby on the focused datum.\nScreen readers announce the tooltip fields in declared order when the\ndatum receives focus.\n",
        "focusManagement": "Focus remains on the data mark, not the tooltip. The tooltip is a non-modal\noverlay that follows the focused element. Dismissal returns no focus change.\n"
      },
      "examples": [
        "RevenueByRegionTooltip",
        "UserActivityHoverDetail"
      ],
      "references": [
        "WCAG 2.1 SC 1.4.13 — Content on Hover or Focus",
        "RDS.7 Trait-Driven Visualization System Specification (v0.1)"
      ]
    },
    "objects": [],
    "source": "traits/viz/interaction-tooltip.trait.yaml"
  },
  "Labelled": {
    "name": "Labelled",
    "version": "2.0.0",
    "description": "Canonical label, description, and placeholder copy for authored objects.\nLabelled is a foundational content trait used by Organization, Product,\nRelationship, and other core objects to provide consistent text display\nacross all view contexts.\n\nSupports configurable length constraints, required/optional description,\nand copy variants (e.g., primary, short, formal) for context-sensitive\ntext rendering.",
    "category": "content",
    "tags": [
      "label",
      "description",
      "copy",
      "metadata",
      "content"
    ],
    "contexts": [
      "card",
      "detail",
      "form",
      "inline",
      "list",
      "timeline"
    ],
    "viewExtensions": [
      {
        "component": "LabelCell",
        "context": "list",
        "position": null,
        "priority": 100,
        "props": {
          "field": "label",
          "descriptionField": "description",
          "truncate": true,
          "maxLengthParameter": "maxLabelLength"
        }
      },
      {
        "component": "DetailHeader",
        "context": "detail",
        "position": "top",
        "priority": 100,
        "props": {
          "titleField": "label",
          "subtitleField": "description",
          "headingLevel": 1
        }
      },
      {
        "component": "FormLabelGroup",
        "context": "form",
        "position": "before",
        "priority": 100,
        "props": {
          "labelField": "label",
          "descriptionField": "description",
          "placeholderField": "placeholder",
          "maxLabelLengthParameter": "maxLabelLength",
          "maxDescriptionLengthParameter": "maxDescriptionLength",
          "requireDescriptionParameter": "requireDescription"
        }
      },
      {
        "component": "CardHeader",
        "context": "card",
        "position": "top",
        "priority": 100,
        "props": {
          "titleField": "label",
          "supportingField": "description"
        }
      },
      {
        "component": "TimelineEntryLabel",
        "context": "timeline",
        "position": null,
        "priority": null,
        "props": {
          "field": "label",
          "compact": true
        }
      },
      {
        "component": "InlineLabel",
        "context": "inline",
        "position": null,
        "priority": null,
        "props": {
          "field": "label",
          "maxLength": 40
        }
      }
    ],
    "parameters": [
      {
        "name": "maxLabelLength",
        "type": "number",
        "required": false,
        "description": "Maximum character length for the label field. Enforced at schema validation and echoed to UI components for truncation.",
        "default": 80,
        "validation": {
          "minimum": 1,
          "maximum": 255
        }
      },
      {
        "name": "maxDescriptionLength",
        "type": "number",
        "required": false,
        "description": "Maximum character length for the description field. Controls form input limits and detail view truncation.",
        "default": 160,
        "validation": {
          "minimum": 1,
          "maximum": 1000
        }
      },
      {
        "name": "requireDescription",
        "type": "boolean",
        "required": false,
        "description": "When true, description becomes a required field. Useful for objects\nwhere supporting text is essential (e.g., Knowledge Articles).\n",
        "default": false
      },
      {
        "name": "copyVariants",
        "type": "string[]",
        "required": false,
        "description": "Named copy variants available for context-sensitive rendering.\n\"primary\" is the default label. Additional variants (e.g., \"short\", \"formal\")\ncan be used for list truncation, exports, or formal documents.\n",
        "default": [
          "primary"
        ]
      }
    ],
    "schema": {
      "label": {
        "type": "string",
        "required": true,
        "description": "Human-readable display name rendered in primary surfaces.",
        "validation": {
          "minLength": 1,
          "maxLengthFromParameter": "maxLabelLength",
          "pattern": "^\\S.*\\S$|^\\S$"
        }
      },
      "description": {
        "type": "string",
        "required": false,
        "requiredFromParameter": "requireDescription",
        "description": "Supporting description used in detail and card contexts.",
        "validation": {
          "maxLengthFromParameter": "maxDescriptionLength"
        }
      },
      "placeholder": {
        "type": "string",
        "required": false,
        "description": "Hint copy surfaced in form fields when the label is empty.",
        "validation": {
          "maxLength": 80
        }
      }
    },
    "semantics": {
      "label": {
        "semantic_type": "text.label",
        "token_mapping": "tokenMap(text.label.*)",
        "ui_hints": {
          "component": "TextHeading",
          "maxLengthParameter": "maxLabelLength",
          "headingLevel": 2
        }
      },
      "description": {
        "semantic_type": "text.description",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "TextBody",
          "maxLengthParameter": "maxDescriptionLength"
        }
      },
      "placeholder": {
        "semantic_type": "text.placeholder",
        "token_mapping": "tokenMap(text.placeholder.*)",
        "ui_hints": {
          "component": "FormHint",
          "maxLength": 80
        }
      }
    },
    "tokens": {
      "text.label.color": "var(--sys-text-strong)",
      "text.label.font-weight": "var(--sys-font-weight-semibold)",
      "text.label.font-size": "var(--sys-font-size-lg)",
      "text.label.line-height": "var(--sys-line-height-tight)",
      "text.body.color": "var(--sys-text-subtle)",
      "text.body.font-weight": "var(--sys-font-weight-regular)",
      "text.body.font-size": "var(--sys-font-size-sm)",
      "text.body.line-height": "var(--sys-line-height-relaxed)",
      "text.placeholder.color": "var(--sys-text-muted)",
      "text.placeholder.font-weight": "var(--sys-font-weight-regular)",
      "text.placeholder.font-size": "var(--sys-font-size-sm)",
      "text.placeholder.line-height": "var(--sys-line-height-normal)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-10-12",
      "updated": "2026-02-28",
      "owners": [
        "Design team",
        "Uxcopy team"
      ],
      "maturity": "stable",
      "accessibility": {
        "keyboard": "FormLabelGroup fields are focusable in reading order with standard tab navigation.",
        "screenreader": "Label is announced as a heading (level configurable via headingLevel prop).\nDescription is announced as supplementary text associated with the heading.\nPlaceholder is announced as input hint via aria-placeholder.\n"
      },
      "regionsUsed": [
        "list",
        "detail",
        "form",
        "card",
        "timeline",
        "inline"
      ],
      "examples": [
        "Organization",
        "Product",
        "Relationship",
        "Ticket",
        "Knowledge Article"
      ],
      "references": [
        "Trait Engine Spec v0.1 §2 — foundational trait definitions",
        "objects/core/Organization.object.yaml — consumer",
        "objects/core/Product.object.yaml — consumer",
        "objects/core/Relationship.object.yaml — consumer"
      ]
    },
    "objects": [
      "Article",
      "Media",
      "Organization",
      "Product",
      "Relationship"
    ],
    "source": "traits/content/Labelled.trait.yaml"
  },
  "LayoutConcat": {
    "name": "LayoutConcat",
    "version": "0.2.0",
    "description": "Defines dashboard-style concatenation for coordinated multi-view experiences.",
    "category": "viz.layout",
    "tags": [
      "viz",
      "layout",
      "concat",
      "dashboard"
    ],
    "contexts": [],
    "viewExtensions": [],
    "parameters": [
      {
        "name": "direction",
        "type": "string",
        "required": false,
        "description": "Primary axis used to arrange concatenated sections.",
        "default": "horizontal",
        "validation": {
          "enum": [
            "horizontal",
            "vertical",
            "grid"
          ]
        }
      },
      {
        "name": "gap",
        "type": "number",
        "required": false,
        "description": "Gap (px) between concatenated sections.",
        "default": 24,
        "validation": {
          "minimum": 0,
          "maximum": 96
        }
      },
      {
        "name": "sharedChannels",
        "type": "string[]",
        "required": false,
        "description": "Channels propagated across concatenated children.",
        "default": [
          "color"
        ]
      },
      {
        "name": "maxSections",
        "type": "number",
        "required": false,
        "description": "Maximum number of child sections governed by this layout.",
        "default": 4,
        "validation": {
          "minimum": 2,
          "maximum": 12
        }
      },
      {
        "name": "projection",
        "type": "string",
        "required": false,
        "description": "Projection hint consumed by adapters.",
        "default": "cartesian",
        "validation": {
          "enum": [
            "cartesian",
            "polar",
            "radial"
          ]
        }
      }
    ],
    "schema": {
      "viz_layout_type": {
        "type": "string",
        "required": true,
        "description": "Normalized layout identifier.",
        "default": "concat",
        "validation": {
          "enum": [
            "concat"
          ]
        }
      },
      "viz_layout_direction": {
        "type": "string",
        "required": false,
        "description": "Axis used for arranging concatenated sections.",
        "defaultFromParameter": "direction",
        "validation": {
          "enum": [
            "horizontal",
            "vertical",
            "grid"
          ]
        }
      },
      "viz_layout_gap": {
        "type": "number",
        "required": false,
        "description": "Gap (px) between concatenated sections.",
        "defaultFromParameter": "gap",
        "validation": {
          "minimum": 0,
          "maximum": 96
        }
      },
      "viz_layout_shared_channels": {
        "type": "string[]",
        "required": false,
        "description": "Channels whose domains remain shared across sections.",
        "defaultFromParameter": "sharedChannels"
      },
      "viz_layout_max_sections": {
        "type": "number",
        "required": false,
        "description": "Maximum section count before warning triggers.",
        "defaultFromParameter": "maxSections",
        "validation": {
          "minimum": 2,
          "maximum": 12
        }
      },
      "viz_layout_projection": {
        "type": "string",
        "required": false,
        "description": "Projection metadata forwarded to adapters.",
        "defaultFromParameter": "projection",
        "validation": {
          "enum": [
            "cartesian",
            "polar",
            "radial"
          ]
        }
      }
    },
    "semantics": {
      "viz_layout_type": {
        "semantic_type": "viz.layout.type",
        "ui_hints": {
          "component": "Badge"
        }
      },
      "viz_layout_direction": {
        "semantic_type": "viz.layout.concat.direction",
        "ui_hints": {
          "component": "Badge"
        }
      },
      "viz_layout_gap": {
        "semantic_type": "viz.layout.spacing",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "px"
        }
      },
      "viz_layout_shared_channels": {
        "semantic_type": "viz.layout.shared_channels",
        "ui_hints": {
          "component": "ListSummary"
        }
      },
      "viz_layout_max_sections": {
        "semantic_type": "viz.layout.concat.sections",
        "ui_hints": {
          "component": "NumericPreview"
        }
      },
      "viz_layout_projection": {
        "semantic_type": "viz.layout.projection",
        "ui_hints": {
          "component": "Badge"
        }
      }
    },
    "tokens": {
      "viz.layout.concat.gap": "var(--cmp-viz-layout-gap)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-16",
      "updated": "2026-02-28",
      "owners": [
        "Viz team"
      ],
      "maturity": "beta",
      "accessibility": {
        "keyboard": "Concatenated sections are keyboard-navigable as a section group. Tab moves between sections.",
        "screenreader": "Announces section count and shared channels (e.g., \"Dashboard with 3 sections, shared color scale\")."
      },
      "examples": [
        "RevenueDashboard",
        "SupportMetricsOverview",
        "SalesFunnelWithBreakdown"
      ],
      "references": [
        "objects/provenance.v1.json#/references/ref-c52ae10b7f25"
      ]
    },
    "objects": [],
    "source": "traits/viz/layout-concat.trait.yaml"
  },
  "LayoutFacet": {
    "name": "LayoutFacet",
    "version": "0.2.0",
    "description": "Repeats a normalized visualization spec across a governed facet grid so row and column groupings stay synchronized with shared color/scale semantics.",
    "category": "viz.layout",
    "tags": [
      "viz",
      "layout",
      "facet",
      "grid"
    ],
    "contexts": [],
    "viewExtensions": [],
    "parameters": [
      {
        "name": "rowField",
        "type": "string",
        "required": false,
        "description": "Field used to create facet rows."
      },
      {
        "name": "columnField",
        "type": "string",
        "required": false,
        "description": "Field used to create facet columns."
      },
      {
        "name": "wrapDirection",
        "type": "string",
        "required": false,
        "description": "Direction to wrap when panels exceed the budget.",
        "default": "row",
        "validation": {
          "enum": [
            "row",
            "column",
            "auto"
          ]
        }
      },
      {
        "name": "maxPanels",
        "type": "number",
        "required": false,
        "description": "Maximum panel count rendered simultaneously.",
        "default": 6,
        "validation": {
          "minimum": 1,
          "maximum": 48
        }
      },
      {
        "name": "sharedChannels",
        "type": "string[]",
        "required": false,
        "description": "Encoding channels that remain synchronized across panels.",
        "default": [
          "x",
          "y",
          "color"
        ]
      },
      {
        "name": "projection",
        "type": "string",
        "required": false,
        "description": "Projection hint consumed by downstream adapters.",
        "default": "cartesian",
        "validation": {
          "enum": [
            "cartesian",
            "polar",
            "radial"
          ]
        }
      }
    ],
    "schema": {
      "viz_layout_type": {
        "type": "string",
        "required": true,
        "description": "Normalized layout identifier.",
        "default": "facet",
        "validation": {
          "enum": [
            "facet"
          ]
        }
      },
      "viz_layout_rows_field": {
        "type": "string",
        "required": false,
        "description": "Data field used to derive facet rows.",
        "defaultFromParameter": "rowField"
      },
      "viz_layout_columns_field": {
        "type": "string",
        "required": false,
        "description": "Data field used to derive facet columns.",
        "defaultFromParameter": "columnField"
      },
      "viz_layout_wrap_direction": {
        "type": "string",
        "required": false,
        "description": "How facets wrap when exceeding panel limits.",
        "defaultFromParameter": "wrapDirection",
        "validation": {
          "enum": [
            "row",
            "column",
            "auto"
          ]
        }
      },
      "viz_layout_max_panels": {
        "type": "number",
        "required": false,
        "description": "Maximum panel count rendered simultaneously.",
        "defaultFromParameter": "maxPanels",
        "validation": {
          "minimum": 1,
          "maximum": 48
        }
      },
      "viz_layout_shared_channels": {
        "type": "string[]",
        "required": false,
        "description": "Channels whose domains remain shared across panels.",
        "defaultFromParameter": "sharedChannels"
      },
      "viz_layout_projection": {
        "type": "string",
        "required": false,
        "description": "Projection metadata forwarded to adapters and docs.",
        "defaultFromParameter": "projection",
        "validation": {
          "enum": [
            "cartesian",
            "polar",
            "radial"
          ]
        }
      },
      "viz_layout_gap": {
        "type": "number",
        "required": false,
        "description": "Gap (px) between panels.",
        "default": 16,
        "validation": {
          "minimum": 0,
          "maximum": 64
        }
      }
    },
    "semantics": {
      "viz_layout_type": {
        "semantic_type": "viz.layout.type",
        "ui_hints": {
          "component": "Badge"
        }
      },
      "viz_layout_rows_field": {
        "semantic_type": "viz.layout.facet.rows",
        "ui_hints": {
          "component": "Code"
        }
      },
      "viz_layout_columns_field": {
        "semantic_type": "viz.layout.facet.columns",
        "ui_hints": {
          "component": "Code"
        }
      },
      "viz_layout_wrap_direction": {
        "semantic_type": "viz.layout.facet.wrap",
        "ui_hints": {
          "component": "Badge"
        }
      },
      "viz_layout_max_panels": {
        "semantic_type": "viz.layout.facet.panels",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "panels"
        }
      },
      "viz_layout_shared_channels": {
        "semantic_type": "viz.layout.shared_channels",
        "ui_hints": {
          "component": "ListSummary"
        }
      },
      "viz_layout_projection": {
        "semantic_type": "viz.layout.projection",
        "ui_hints": {
          "component": "Badge"
        }
      },
      "viz_layout_gap": {
        "semantic_type": "viz.layout.spacing",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "px"
        }
      }
    },
    "tokens": {
      "viz.layout.facet.gap": "var(--cmp-viz-layout-gap)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-16",
      "updated": "2026-02-28",
      "owners": [
        "Viz team"
      ],
      "maturity": "beta",
      "accessibility": {
        "keyboard": "Facet panels are navigable via arrow keys. Each panel is a tab stop.",
        "screenreader": "Announces facet field name and panel count (e.g., \"Faceted by Region, 6 panels\")."
      },
      "examples": [
        "SalesByRegionFaceted",
        "ChurnByPlanType",
        "TicketVolumeByCategoryAndMonth"
      ],
      "references": [
        "objects/provenance.v1.json#/references/ref-c52ae10b7f25",
        "Sprint 23 plan"
      ]
    },
    "objects": [],
    "source": "traits/viz/layout-facet.trait.yaml"
  },
  "LayoutLayer": {
    "name": "LayoutLayer",
    "version": "0.2.0",
    "description": "Governs sequencing, blending, and shared channel behavior for layered mark compositions.",
    "category": "viz.layout",
    "tags": [
      "viz",
      "layout",
      "layer",
      "composition"
    ],
    "contexts": [],
    "viewExtensions": [],
    "parameters": [
      {
        "name": "blendMode",
        "type": "string",
        "required": false,
        "description": "Blend/composite mode applied across stacked marks.",
        "default": "normal",
        "validation": {
          "enum": [
            "normal",
            "multiply",
            "screen",
            "overlay"
          ]
        }
      },
      {
        "name": "syncInteractions",
        "type": "boolean",
        "required": false,
        "description": "Whether interaction predicates propagate across all layers.",
        "default": true
      },
      {
        "name": "sharedChannels",
        "type": "string[]",
        "required": false,
        "description": "Channels whose scales remain synchronized across layers.",
        "default": [
          "x",
          "y",
          "color"
        ]
      },
      {
        "name": "orderHint",
        "type": "string[]",
        "required": false,
        "description": "Optional list describing explicit bottom→top layer ordering. Entries name layers by mark options.id when set (preferred — repeated same-trait marks need distinct ids to be addressable), else by mark trait."
      },
      {
        "name": "projection",
        "type": "string",
        "required": false,
        "description": "Projection hint for adapters when layering across spaces.",
        "default": "cartesian",
        "validation": {
          "enum": [
            "cartesian",
            "polar",
            "radial"
          ]
        }
      }
    ],
    "schema": {
      "viz_layout_type": {
        "type": "string",
        "required": true,
        "description": "Normalized layout identifier.",
        "default": "layer",
        "validation": {
          "enum": [
            "layer"
          ]
        }
      },
      "viz_layout_blend_mode": {
        "type": "string",
        "required": false,
        "description": "Blend/composite mode applied to layered marks.",
        "defaultFromParameter": "blendMode",
        "validation": {
          "enum": [
            "normal",
            "multiply",
            "screen",
            "overlay"
          ]
        }
      },
      "viz_layout_sync_interactions": {
        "type": "boolean",
        "required": false,
        "description": "Whether interaction predicates are shared across layers.",
        "defaultFromParameter": "syncInteractions"
      },
      "viz_layout_shared_channels": {
        "type": "string[]",
        "required": false,
        "description": "Channels that share a domain across layered marks.",
        "defaultFromParameter": "sharedChannels"
      },
      "viz_layout_order_hint": {
        "type": "string[]",
        "required": false,
        "description": "Optional ordered list describing layer precedence.",
        "defaultFromParameter": "orderHint"
      },
      "viz_layout_projection": {
        "type": "string",
        "required": false,
        "description": "Projection metadata forwarded to adapters and docs.",
        "defaultFromParameter": "projection",
        "validation": {
          "enum": [
            "cartesian",
            "polar",
            "radial"
          ]
        }
      }
    },
    "semantics": {
      "viz_layout_type": {
        "semantic_type": "viz.layout.type",
        "ui_hints": {
          "component": "Badge"
        }
      },
      "viz_layout_blend_mode": {
        "semantic_type": "viz.layout.layer.blend",
        "ui_hints": {
          "component": "Badge"
        }
      },
      "viz_layout_sync_interactions": {
        "semantic_type": "viz.layout.layer.sync_interactions",
        "ui_hints": {
          "component": "BooleanPill"
        }
      },
      "viz_layout_shared_channels": {
        "semantic_type": "viz.layout.shared_channels",
        "ui_hints": {
          "component": "ListSummary"
        }
      },
      "viz_layout_order_hint": {
        "semantic_type": "viz.layout.layer.order",
        "ui_hints": {
          "component": "ListSummary"
        }
      },
      "viz_layout_projection": {
        "semantic_type": "viz.layout.projection",
        "ui_hints": {
          "component": "Badge"
        }
      }
    },
    "tokens": {
      "viz.layout.layer.blend": "var(--cmp-viz-layer-blend)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-16",
      "updated": "2026-02-28",
      "owners": [
        "Viz team"
      ],
      "maturity": "beta",
      "accessibility": {
        "keyboard": "Layer order is keyboard-traversable. Focus moves through layers bottom to top.",
        "screenreader": "Announces layer count and blend mode (e.g., \"Layered visualization, 3 layers, normal blend\")."
      },
      "examples": [
        "LineWithConfidenceBand",
        "BarWithTrendOverlay",
        "ScatterWithRegressionLine"
      ],
      "references": [
        "objects/provenance.v1.json#/references/ref-c52ae10b7f25"
      ]
    },
    "objects": [],
    "source": "traits/viz/layout-layer.trait.yaml"
  },
  "Mandate": {
    "name": "Mandate",
    "version": "1.1.1",
    "description": "The record of a grant: a standing yes that one actor may act for a person or organization, on stated terms,\nuntil it ends. It keeps who asked for it, who gave it and in what capacity, who holds it and who it is for; what it\ncovers in words, its three lines for that party, its limits and its end; its use as the product counts it; the\ngrant it sits inside or replaced; and who ended it and why. The Grant object composes this trait, and the importer\ncan propose it for another system's grant or consent record that keeps a state, an end and the agent or app that\nholds it, so every field lives here and a proposal can bind what the source has.\n\nThe state of the grant is not a field of this trait. It is the record's own lifecycle, through Stateful: for a\nGrant, requested, then active (or paused), declined or withdrawn, or expired when no one answers in time; a grant\nonce given ends revoked, expired or replaced. Its terms are not\nedited in place. A change of terms is a new grant that names the one it replaces, and a standing yes for one\naction is a new grant inside the first, with its own bounds and end.\n\nA reference to a person, an agent, an organization or another grant is an id and a kept name, so it still reads\nafter the person leaves or the grant ends. The kinds are the Actor trait's three words: person, agent or system.\nThe three lines follow the Agent's own: items separated by \"; \", and \"None\" when there are none. The money limits\nare whole numbers in the currency's minor units at two decimal places, so a currency with other decimals reads\nwrong. The end is kept three ways: the exact instant a product checks, the party's time zone, and one line in the\nparty's own words and zone, which is what people read.\n\nOODS Foundry keeps and shows this record. It does not check a grant against what an actor does, count its uses or\nspend, expire or renew one, stop a token or decide whether an action was allowed. A generated app's Revoke, Pause\nand Resume change the record when a person asks, and stop nothing outside it.",
    "category": "core",
    "tags": [
      "grant-record",
      "standing-yes",
      "actor-reference",
      "kept-terms"
    ],
    "contexts": [
      "card",
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "LabelCell",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "field": "granted_to_id",
          "description": "Held by",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "LabelCell",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "field": "granted_for_id",
          "description": "For",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "LabelCell",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "field": "ends_note",
          "description": "Ends",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "LabelCell",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "field": "last_use",
          "description": "Last used for",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "LabelCell",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "field": "granted_to_id",
          "description": "Held by",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "LabelCell",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "field": "granted_for_id",
          "description": "For",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "LabelCell",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "field": "ends_note",
          "description": "Ends",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 90,
        "props": {
          "field": "scope",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 89,
        "props": {
          "field": "granted_for_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 88,
        "props": {
          "field": "granted_for_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 87,
        "props": {
          "field": "granted_to_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 86,
        "props": {
          "field": "granted_to_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 85,
        "props": {
          "field": "granted_to_kind",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 84,
        "props": {
          "field": "granted_by_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 83,
        "props": {
          "field": "granted_by_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 82,
        "props": {
          "field": "granted_by_kind",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 81,
        "props": {
          "field": "granted_as",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 80,
        "props": {
          "field": "requested_by_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 79,
        "props": {
          "field": "requested_by_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 78,
        "props": {
          "field": "requested_by_kind",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 77.9,
        "props": {
          "field": "asked_of_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 77.8,
        "props": {
          "field": "asked_of_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 77.7,
        "props": {
          "field": "asked_of_kind",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 77,
        "props": {
          "field": "allowed_actions",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 76,
        "props": {
          "field": "asks_first_for",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 75,
        "props": {
          "field": "never_allowed",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 74,
        "props": {
          "field": "amount_limit_minor",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 73,
        "props": {
          "field": "period_limit_minor",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 72,
        "props": {
          "field": "limit_period",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 71,
        "props": {
          "field": "uses_per_period",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 70,
        "props": {
          "field": "conditions",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 69,
        "props": {
          "field": "ends_note",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 68,
        "props": {
          "field": "ends_at",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 67,
        "props": {
          "field": "timezone",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 66,
        "props": {
          "field": "uses",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 65,
        "props": {
          "field": "last_used_at",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 64,
        "props": {
          "field": "last_use",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 63,
        "props": {
          "field": "spent_minor",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 62,
        "props": {
          "field": "within_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 61,
        "props": {
          "field": "within_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 60,
        "props": {
          "field": "replaces_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 59,
        "props": {
          "field": "replaces_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 58,
        "props": {
          "field": "first_grant_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 57,
        "props": {
          "field": "first_grant_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 56,
        "props": {
          "field": "ended_by_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 55,
        "props": {
          "field": "ended_by_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 54,
        "props": {
          "field": "ended_by_kind",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 53.5,
        "props": {
          "field": "ended_as",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 53,
        "props": {
          "field": "ended_reason",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 90,
        "props": {
          "field": "scope",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 89,
        "props": {
          "field": "granted_for_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 88,
        "props": {
          "field": "granted_for_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 87,
        "props": {
          "field": "granted_to_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 86,
        "props": {
          "field": "granted_to_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 85,
        "props": {
          "field": "granted_by_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 84,
        "props": {
          "field": "granted_by_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 83,
        "props": {
          "field": "granted_as",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 82,
        "props": {
          "field": "requested_by_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 81,
        "props": {
          "field": "requested_by_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 80.9,
        "props": {
          "field": "asked_of_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 80.8,
        "props": {
          "field": "asked_of_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 80,
        "props": {
          "field": "allowed_actions",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 79,
        "props": {
          "field": "asks_first_for",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 78,
        "props": {
          "field": "never_allowed",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 77,
        "props": {
          "field": "amount_limit_minor",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 76,
        "props": {
          "field": "period_limit_minor",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 75,
        "props": {
          "field": "limit_period",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 74,
        "props": {
          "field": "uses_per_period",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 73,
        "props": {
          "field": "conditions",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 72,
        "props": {
          "field": "ends_note",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 71,
        "props": {
          "field": "ends_at",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 70,
        "props": {
          "field": "within_id",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Text",
        "context": "form",
        "position": "top",
        "priority": 69,
        "props": {
          "field": "within_name",
          "data-oods-omit-empty": true
        }
      },
      {
        "component": "Input",
        "context": "form",
        "position": "main",
        "priority": 60,
        "props": {
          "field": "ended_reason",
          "label": "Why it is ending, if you end it here"
        }
      }
    ],
    "parameters": [],
    "schema": {
      "requested_by_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who asked for the grant, by the id the product knows them by: a person, or the agent itself."
      },
      "requested_by_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who asked for the grant, as shown (\"Billing Agent\"). Kept on the record."
      },
      "requested_by_kind": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What kind of actor asked for it (person, agent or system), as the Actor trait names them.",
        "validation": {
          "enum": [
            "person",
            "agent",
            "system"
          ]
        }
      },
      "asked_of_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who was asked for the yes, by the id the product knows them by. A requested grant waits on them; the field stays once it is answered."
      },
      "asked_of_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who was asked for the yes, as shown (\"Ruth Adeyemi\"). Kept on the record."
      },
      "asked_of_kind": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What kind of actor was asked for the yes (person, agent or system), as the Actor trait names them.",
        "validation": {
          "enum": [
            "person",
            "agent",
            "system"
          ]
        }
      },
      "granted_by_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who gave the grant, by the id the product knows them by: usually a person who may give it for the party."
      },
      "granted_by_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who gave the grant, as shown (\"Ruth Adeyemi\"). Kept on the record, so it still reads after they leave."
      },
      "granted_by_kind": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What kind of actor gave it (person, agent or system), as the Actor trait names them.",
        "validation": {
          "enum": [
            "person",
            "agent",
            "system"
          ]
        }
      },
      "granted_as": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The capacity the giver gave it in, in one line (\"Finance manager, Tidewater Co-op\").",
        "validation": {
          "maxLength": 120
        }
      },
      "granted_to_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who holds the grant and acts under it, by the id the product knows them by: an agent, or a person standing in for someone."
      },
      "granted_to_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who holds the grant, as shown (\"Billing Agent\"). Kept on the record."
      },
      "granted_to_kind": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What kind of actor holds it (person, agent or system), as the Actor trait names them.",
        "validation": {
          "enum": [
            "person",
            "agent",
            "system"
          ]
        }
      },
      "granted_for_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who the grant is for, the person or organization the holder acts for, by the id the product knows them by. Never an agent."
      },
      "granted_for_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who the grant is for, as shown (\"Tidewater Co-op\"). Kept on the record."
      },
      "scope": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What the grant covers, in a few words (\"Invoices and payments\").",
        "validation": {
          "maxLength": 160
        }
      },
      "allowed_actions": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Actions the holder may take for this party with no one asked, separated by \"; \"; None when there are none."
      },
      "asks_first_for": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Actions that need a person's yes before the holder takes them for this party, separated by \"; \"; None when there are none."
      },
      "never_allowed": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Actions the holder never takes for this party, separated by \"; \"; None when there are none. An action for the party that no line names is never allowed; asking the person who gave it for a yes or an answer is not one."
      },
      "amount_limit_minor": {
        "type": "integer",
        "required": false,
        "readOnly": true,
        "description": "The most the holder may move in one use, in the currency's minor units (1200000 is $12,000.00).",
        "validation": {
          "minimum": 0
        }
      },
      "period_limit_minor": {
        "type": "integer",
        "required": false,
        "readOnly": true,
        "description": "The most the holder may move in each period, in the currency's minor units.",
        "validation": {
          "minimum": 0
        }
      },
      "limit_currency": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The currency of the money limits, as an ISO 4217 code (\"USD\").",
        "validation": {
          "pattern": "^[A-Z]{3}$"
        }
      },
      "limit_period": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The period the limits per period count over.",
        "validation": {
          "enum": [
            "day",
            "week",
            "month",
            "year"
          ]
        }
      },
      "uses_per_period": {
        "type": "integer",
        "required": false,
        "readOnly": true,
        "description": "The most times the grant may be used in each period.",
        "validation": {
          "minimum": 0
        }
      },
      "conditions": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Conditions on each use, in words, shown and not checked (\"Only a payment the bank returned, to the same payee for the same amount\").",
        "validation": {
          "maxLength": 240
        }
      },
      "ends_at": {
        "type": "datetime",
        "required": false,
        "readOnly": true,
        "description": "The exact instant the grant ends, the one a product checks.",
        "validation": {
          "format": "date-time"
        }
      },
      "timezone": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The party's time zone, as an IANA name (\"Pacific/Auckland\"), the zone its end is read in.",
        "validation": {
          "maxLength": 64
        }
      },
      "ends_note": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The end as people read it, in the party's own words and time zone (\"At the end of 31 Dec 2026, Tauranga time\"), written by the product; a grant with no end says so here (\"No end: it stands until someone ends it\").",
        "validation": {
          "maxLength": 160
        }
      },
      "uses": {
        "type": "integer",
        "required": false,
        "readOnly": true,
        "description": "How many times the grant has been used, as the product counts it.",
        "validation": {
          "minimum": 0
        }
      },
      "last_used_at": {
        "type": "datetime",
        "required": false,
        "readOnly": true,
        "description": "When the grant was last used.",
        "validation": {
          "format": "date-time"
        }
      },
      "last_use": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The last use, in one kept line (\"28 Sep: PAY-2026-0429 sent again\").",
        "validation": {
          "maxLength": 240
        }
      },
      "spent_minor": {
        "type": "integer",
        "required": false,
        "readOnly": true,
        "description": "The money moved under the grant in the current period, as the product counts it, in the currency's minor units.",
        "validation": {
          "minimum": 0
        }
      },
      "within_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The grant this one sits inside, for a standing yes given for one action: same holder, same party, ending no later."
      },
      "within_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The grant this one sits inside, as shown. Kept on the record."
      },
      "replaces_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The grant this one replaced when the terms changed; that grant is kept whole, ended as replaced."
      },
      "replaces_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The grant this one replaced, as shown. Kept on the record."
      },
      "first_grant_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The first grant in a line of replacements, kept on every later grant in the line so a search by its name finds them all."
      },
      "first_grant_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The first grant in the line, as shown. Kept on the record."
      },
      "ended_by_id": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who ended the grant, by the id the product knows them by, when someone did."
      },
      "ended_by_name": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "Who ended the grant, as shown. Kept on the record."
      },
      "ended_by_kind": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "What kind of actor ended it (person, agent or system), as the Actor trait names them.",
        "validation": {
          "enum": [
            "person",
            "agent",
            "system"
          ]
        }
      },
      "ended_as": {
        "type": "string",
        "required": false,
        "readOnly": true,
        "description": "The capacity they ended it in, in one line, where it is not one of the grant's own seats (\"Accounts lead, Kestrel Print Co.\").",
        "validation": {
          "maxLength": 120
        }
      },
      "ended_reason": {
        "type": "string",
        "required": false,
        "description": "Why the grant ended, in one line, written where it is ended (\"The studio closed\").",
        "validation": {
          "maxLength": 240
        }
      }
    },
    "semantics": {
      "requested_by_id": {
        "semantic_type": "mandate.requested_by_id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked for by",
          "displayLabelField": "requested_by_name"
        }
      },
      "requested_by_name": {
        "semantic_type": "mandate.requested_by_name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked for by"
        }
      },
      "requested_by_kind": {
        "semantic_type": "mandate.requested_by_kind",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Kind of asker"
        }
      },
      "asked_of_id": {
        "semantic_type": "mandate.asked_of_id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked of",
          "displayLabelField": "asked_of_name"
        }
      },
      "asked_of_name": {
        "semantic_type": "mandate.asked_of_name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asked of"
        }
      },
      "asked_of_kind": {
        "semantic_type": "mandate.asked_of_kind",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Kind of the one asked"
        }
      },
      "granted_by_id": {
        "semantic_type": "mandate.granted_by_id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Given by",
          "displayLabelField": "granted_by_name"
        }
      },
      "granted_by_name": {
        "semantic_type": "mandate.granted_by_name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Given by"
        }
      },
      "granted_by_kind": {
        "semantic_type": "mandate.granted_by_kind",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Kind of giver"
        }
      },
      "granted_as": {
        "semantic_type": "mandate.granted_as",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Given as"
        }
      },
      "granted_to_id": {
        "semantic_type": "mandate.granted_to_id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Held by",
          "displayLabelField": "granted_to_name"
        }
      },
      "granted_to_name": {
        "semantic_type": "mandate.granted_to_name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Held by"
        }
      },
      "granted_to_kind": {
        "semantic_type": "mandate.granted_to_kind",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Kind of holder"
        }
      },
      "granted_for_id": {
        "semantic_type": "mandate.granted_for_id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "For",
          "displayLabelField": "granted_for_name"
        }
      },
      "granted_for_name": {
        "semantic_type": "mandate.granted_for_name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "For"
        }
      },
      "scope": {
        "semantic_type": "mandate.scope",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Covers"
        }
      },
      "allowed_actions": {
        "semantic_type": "mandate.allowed_actions",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Allowed actions"
        }
      },
      "asks_first_for": {
        "semantic_type": "mandate.asks_first_for",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Asks first for",
          "valueLabels": {
            "None": "No listed action needs a separate yes"
          }
        }
      },
      "never_allowed": {
        "semantic_type": "mandate.never_allowed",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Never allowed",
          "valueLabels": {
            "None": "No additional exclusions listed"
          }
        }
      },
      "amount_limit_minor": {
        "semantic_type": "mandate.amount_limit_minor",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "CurrencyAmount",
          "currencyField": "limit_currency",
          "minorUnits": 100,
          "label": "Most per use"
        }
      },
      "period_limit_minor": {
        "semantic_type": "mandate.period_limit_minor",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "CurrencyAmount",
          "currencyField": "limit_currency",
          "minorUnits": 100,
          "label": "Most per period"
        }
      },
      "limit_currency": {
        "semantic_type": "mandate.limit_currency",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Currency"
        }
      },
      "limit_period": {
        "semantic_type": "mandate.limit_period",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Period"
        }
      },
      "uses_per_period": {
        "semantic_type": "mandate.uses_per_period",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Uses per period"
        }
      },
      "conditions": {
        "semantic_type": "mandate.conditions",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Conditions"
        }
      },
      "ends_at": {
        "semantic_type": "mandate.ends_at",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "RelativeTimestamp",
          "label": "End time"
        }
      },
      "timezone": {
        "semantic_type": "mandate.timezone",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Time zone"
        }
      },
      "ends_note": {
        "semantic_type": "mandate.ends_note",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Ends"
        }
      },
      "uses": {
        "semantic_type": "mandate.uses",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Uses"
        }
      },
      "last_used_at": {
        "semantic_type": "mandate.last_used_at",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "RelativeTimestamp",
          "label": "Last used"
        }
      },
      "last_use": {
        "semantic_type": "mandate.last_use",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Last used for"
        }
      },
      "spent_minor": {
        "semantic_type": "mandate.spent_minor",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "CurrencyAmount",
          "currencyField": "limit_currency",
          "minorUnits": 100,
          "label": "Spent this period"
        }
      },
      "within_id": {
        "semantic_type": "mandate.within_id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Inside",
          "displayLabelField": "within_name"
        }
      },
      "within_name": {
        "semantic_type": "mandate.within_name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Inside"
        }
      },
      "replaces_id": {
        "semantic_type": "mandate.replaces_id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Replaces",
          "displayLabelField": "replaces_name"
        }
      },
      "replaces_name": {
        "semantic_type": "mandate.replaces_name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Replaces"
        }
      },
      "first_grant_id": {
        "semantic_type": "mandate.first_grant_id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "First grant",
          "displayLabelField": "first_grant_name"
        }
      },
      "first_grant_name": {
        "semantic_type": "mandate.first_grant_name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "First grant"
        }
      },
      "ended_by_id": {
        "semantic_type": "mandate.ended_by_id",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Ended by",
          "displayLabelField": "ended_by_name"
        }
      },
      "ended_by_name": {
        "semantic_type": "mandate.ended_by_name",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Ended by"
        }
      },
      "ended_by_kind": {
        "semantic_type": "mandate.ended_by_kind",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Kind of ender"
        }
      },
      "ended_as": {
        "semantic_type": "mandate.ended_as",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Ended as"
        }
      },
      "ended_reason": {
        "semantic_type": "mandate.ended_reason",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text",
          "label": "Why it ended",
          "multiline": false
        }
      }
    },
    "tokens": {},
    "dependencies": [
      "Stateful"
    ],
    "metadata": {
      "created": "2026-11-14",
      "owners": [
        "Core team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "The record's facts add no interactive control; on an open grant, why it is ending is a labelled form input.",
        "screenreader": "Each fact is read with its visible label, label first on the detail page and the form (\"Held by, Billing Agent\") and value first on a list row or a card (\"Billing Agent, Held by\")."
      },
      "regionsUsed": [
        "list",
        "card",
        "detail",
        "form"
      ],
      "examples": [
        "Grant"
      ],
      "references": [
        "OAuth 2.0 Rich Authorization Requests (RFC 9396): each item has a type that sets its allowed contents, and names the actions to be taken at the resource",
        "UK Open Banking VRP consents (v4.0.1): a maximum per payment instruction and per period, and values supplied in the consent must not change",
        "FDX 6.6 consent grant: a status of ACTIVE, EXPIRED or REVOKED, with the reason for a revocation and the party that started it",
        "GDPR Article 7(3): It shall be as easy to withdraw as to give consent"
      ]
    },
    "objects": [
      "Grant"
    ],
    "source": "traits/core/Mandate.trait.yaml"
  },
  "MarkArea": {
    "name": "MarkArea",
    "version": "0.2.1",
    "description": "Canonical area mark for cumulative totals and ranges. Fills the region\nbetween the series baseline and value curve with configurable opacity and\ninterpolation.",
    "category": "viz.mark",
    "tags": [
      "viz",
      "mark",
      "area",
      "band"
    ],
    "contexts": [
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "VizAreaPreview",
        "context": "detail",
        "position": "top",
        "priority": 55,
        "props": {
          "curveField": "viz_area_curve",
          "opacityField": "viz_area_opacity",
          "svgParameter": "previewSvg",
          "baselineField": "viz_area_baseline"
        }
      },
      {
        "component": "VizAreaControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "curveField": "viz_area_curve",
          "opacityField": "viz_area_opacity",
          "baselineField": "viz_area_baseline",
          "tensionField": "viz_area_tension"
        }
      },
      {
        "component": "VizRoleBadge",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "labelField": "viz_mark_role"
        }
      }
    ],
    "parameters": [
      {
        "name": "chart",
        "type": "object",
        "required": false,
        "description": "Optional read-only chart declaration binding existing domain fields; projects into supported detail and dashboard views."
      },
      {
        "name": "title",
        "type": "string",
        "required": false,
        "description": "Title for the bound chart and its accessible figure.",
        "default": "Payment amounts"
      },
      {
        "name": "description",
        "type": "string",
        "required": false,
        "description": "Description of the bound chart measurements and units.",
        "default": "Values recorded for this record."
      },
      {
        "name": "previewSvg",
        "type": "string",
        "required": false,
        "description": "Static SVG returned by viz_render for the authored sample."
      },
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment for the governed authoring recipes. Data rows remain a consumer operand."
      },
      {
        "name": "curve",
        "type": "string",
        "required": false,
        "description": "Curve interpolation strategy applied between samples.",
        "default": "linear",
        "validation": {
          "enum": [
            "linear",
            "monotone",
            "step"
          ]
        }
      },
      {
        "name": "opacity",
        "type": "number",
        "required": false,
        "description": "Fill opacity used for the area band.",
        "default": 0.65,
        "validation": {
          "minimum": 0.2,
          "maximum": 1
        }
      },
      {
        "name": "baseline",
        "type": "string",
        "required": false,
        "description": "Baseline reference for filling the region (zero, min, or custom).",
        "default": "zero",
        "validation": {
          "enum": [
            "zero",
            "min"
          ]
        }
      },
      {
        "name": "tension",
        "type": "number",
        "required": false,
        "description": "Curve tension applied when using monotone interpolation.",
        "default": 0.3,
        "validation": {
          "minimum": 0,
          "maximum": 1
        }
      }
    ],
    "schema": {
      "viz_mark_type": {
        "type": "string",
        "required": true,
        "description": "Normalized mark identifier consumed by renderer adapters.",
        "default": "area",
        "validation": {
          "enum": [
            "area"
          ]
        }
      },
      "viz_area_curve": {
        "type": "string",
        "required": false,
        "description": "Interpolation strategy applied between samples.",
        "defaultFromParameter": "curve",
        "validation": {
          "enum": [
            "linear",
            "monotone",
            "step"
          ]
        }
      },
      "viz_area_opacity": {
        "type": "number",
        "required": false,
        "description": "Fill opacity used for the area band.",
        "defaultFromParameter": "opacity",
        "validation": {
          "minimum": 0.2,
          "maximum": 1
        }
      },
      "viz_area_baseline": {
        "type": "string",
        "required": false,
        "description": "Baseline reference for filling the region.",
        "defaultFromParameter": "baseline",
        "validation": {
          "enum": [
            "zero",
            "min"
          ]
        }
      },
      "viz_area_tension": {
        "type": "number",
        "required": false,
        "description": "Curve tension applied when smoothing.",
        "defaultFromParameter": "tension",
        "validation": {
          "minimum": 0,
          "maximum": 1
        }
      },
      "viz_mark_role": {
        "type": "string",
        "required": true,
        "description": "Semantic role for heuristics and docs.",
        "default": "band"
      },
      "viz_mark_a11y_label": {
        "type": "string",
        "required": true,
        "description": "Accessible description fragment for describing area marks.",
        "default": "Area mark representing cumulative or range-based values."
      }
    },
    "semantics": {
      "viz_mark_type": {
        "semantic_type": "viz.mark.type",
        "token_mapping": "tokenMap(viz.mark.type)",
        "ui_hints": {
          "component": "VizMarkSummary"
        }
      },
      "viz_area_curve": {
        "semantic_type": "viz.mark.curve",
        "token_mapping": "tokenMap(viz.mark.curve)",
        "ui_hints": {
          "component": "VizCurveHint"
        }
      },
      "viz_area_opacity": {
        "semantic_type": "viz.mark.opacity",
        "token_mapping": "tokenMap(viz.mark.opacity)",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "opacity"
        }
      },
      "viz_area_baseline": {
        "semantic_type": "viz.mark.baseline",
        "token_mapping": "tokenMap(viz.mark.baseline)",
        "ui_hints": {
          "component": "TextBadge"
        }
      },
      "viz_mark_a11y_label": {
        "semantic_type": "a11y.description",
        "token_mapping": "tokenMap(a11y.chart.description)",
        "ui_hints": {
          "component": "ScreenReaderHint"
        }
      }
    },
    "tokens": {
      "viz.mark.area.fill.default": "var(--cmp-viz-mark-area-fill)",
      "viz.mark.area.opacity.default": "var(--cmp-viz-mark-area-opacity)",
      "viz.mark.area.baseline.stroke": "var(--cmp-viz-axis-base)"
    },
    "dependencies": [
      "EncodingPositionX",
      "EncodingPositionY"
    ],
    "metadata": {
      "created": "2025-11-15",
      "updated": "2026-02-28",
      "owners": [
        "Viz team",
        "Design team"
      ],
      "maturity": "alpha",
      "conflicts_with": [
        "MarkBar",
        "MarkLine",
        "MarkPoint"
      ],
      "accessibility": {
        "rule_reference": "A11Y-R-06",
        "notes": "Convey baseline reference in descriptive text output."
      },
      "regionsUsed": [
        "detail",
        "form",
        "list"
      ],
      "examples": [
        "ForecastRange",
        "BurnDownVariance"
      ],
      "references": [
        "RDS.7 Trait-Driven Visualization System Specification (v0.1)"
      ]
    },
    "objects": [],
    "source": "traits/viz/mark-area.trait.yaml"
  },
  "MarkBar": {
    "name": "MarkBar",
    "version": "0.2.1",
    "description": "Canonical rectangular mark for magnitude comparisons. Supports stacked\nor grouped categories and enforces RDS.7 accessibility requirements for\nredundant encodings.",
    "category": "viz.mark",
    "tags": [
      "viz",
      "mark",
      "bar",
      "comparison"
    ],
    "contexts": [
      "dashboard",
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "VizMarkPreview",
        "context": "detail",
        "position": "top",
        "priority": 60,
        "props": {
          "svgParameter": "previewSvg",
          "typeField": "viz_mark_type",
          "orientationField": "viz_mark_orientation",
          "stackingField": "viz_mark_stacking"
        }
      },
      {
        "component": "VizMarkPreview",
        "context": "dashboard",
        "position": "top",
        "priority": 60,
        "props": {
          "svgParameter": "previewSvg",
          "typeField": "viz_mark_type",
          "orientationField": "viz_mark_orientation",
          "stackingField": "viz_mark_stacking"
        }
      },
      {
        "component": "VizMarkControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "orientationField": "viz_mark_orientation",
          "paddingField": "viz_mark_band_padding",
          "stackingField": "viz_mark_stacking",
          "cornerRadiusField": "viz_mark_corner_radius"
        }
      },
      {
        "component": "VizRoleBadge",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "labelField": "viz_mark_role"
        }
      }
    ],
    "parameters": [
      {
        "name": "chart",
        "type": "object",
        "required": false,
        "description": "Optional read-only chart declaration binding existing domain fields; projects into supported detail and dashboard views."
      },
      {
        "name": "title",
        "type": "string",
        "required": false,
        "description": "Title for the bound chart and its accessible figure."
      },
      {
        "name": "description",
        "type": "string",
        "required": false,
        "description": "Description of the bound chart measurements and units."
      },
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment for the governed authoring recipes. Data rows remain a consumer operand."
      },
      {
        "name": "previewSvg",
        "type": "string",
        "required": false,
        "description": "Static SVG returned by viz_render for the authored sample; omitted until a chart is rendered."
      },
      {
        "name": "orientation",
        "type": "string",
        "required": true,
        "description": "Axis orientation used for laying out bar rectangles.",
        "default": "vertical",
        "validation": {
          "enum": [
            "vertical",
            "horizontal"
          ]
        }
      },
      {
        "name": "bandPadding",
        "type": "number",
        "required": false,
        "description": "Fractional padding between category bands (0-0.5).",
        "default": 0.1,
        "validation": {
          "minimum": 0,
          "maximum": 0.5
        }
      },
      {
        "name": "cornerRadius",
        "type": "number",
        "required": false,
        "description": "Pixel radius applied to bar corners.",
        "default": 2,
        "validation": {
          "minimum": 0,
          "maximum": 12
        }
      },
      {
        "name": "stacking",
        "type": "string",
        "required": false,
        "description": "Aggregation strategy when multiple series share the mark.",
        "default": "auto",
        "validation": {
          "enum": [
            "auto",
            "normalize",
            "none"
          ]
        }
      }
    ],
    "schema": {
      "viz_mark_type": {
        "type": "string",
        "required": true,
        "description": "Normalized mark identifier consumed by renderer adapters.",
        "default": "bar",
        "validation": {
          "enum": [
            "bar"
          ]
        }
      },
      "viz_mark_orientation": {
        "type": "string",
        "required": true,
        "description": "Orientation flag for aligning axes and fallbacks.",
        "defaultFromParameter": "orientation",
        "validation": {
          "enum": [
            "vertical",
            "horizontal"
          ]
        }
      },
      "viz_mark_band_padding": {
        "type": "number",
        "required": false,
        "description": "Fractional padding between bars within a category.",
        "defaultFromParameter": "bandPadding",
        "validation": {
          "minimum": 0,
          "maximum": 0.5
        }
      },
      "viz_mark_corner_radius": {
        "type": "number",
        "required": false,
        "description": "Corner radius applied to rendered bars.",
        "defaultFromParameter": "cornerRadius",
        "validation": {
          "minimum": 0,
          "maximum": 12
        }
      },
      "viz_mark_stacking": {
        "type": "string",
        "required": false,
        "description": "Stacking semantics applied to grouped series.",
        "defaultFromParameter": "stacking",
        "validation": {
          "enum": [
            "auto",
            "normalize",
            "none"
          ]
        }
      },
      "viz_mark_role": {
        "type": "string",
        "required": true,
        "description": "Semantic role used by heuristics, docs, and filtering.",
        "default": "comparison"
      },
      "viz_mark_a11y_label": {
        "type": "string",
        "required": true,
        "description": "Accessible description fragment for assistive tech fallbacks.",
        "default": "Bar mark showing magnitude per category."
      }
    },
    "semantics": {
      "viz_mark_type": {
        "semantic_type": "viz.mark.type",
        "token_mapping": "tokenMap(viz.mark.type)",
        "ui_hints": {
          "component": "VizMarkSummary"
        }
      },
      "viz_mark_orientation": {
        "semantic_type": "viz.mark.orientation",
        "token_mapping": "tokenMap(viz.mark.orientation)",
        "ui_hints": {
          "component": "VizOrientationBadge"
        }
      },
      "viz_mark_band_padding": {
        "semantic_type": "viz.mark.spacing",
        "token_mapping": "tokenMap(viz.mark.spacing)",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "fraction"
        }
      },
      "viz_mark_corner_radius": {
        "semantic_type": "viz.mark.corner_radius",
        "token_mapping": "tokenMap(viz.mark.corner_radius)",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "px"
        }
      },
      "viz_mark_stacking": {
        "semantic_type": "viz.mark.stacking",
        "token_mapping": "tokenMap(viz.mark.stacking)",
        "ui_hints": {
          "component": "VizStackingHint"
        }
      },
      "viz_mark_a11y_label": {
        "semantic_type": "a11y.description",
        "token_mapping": "tokenMap(a11y.chart.description)",
        "ui_hints": {
          "component": "ScreenReaderHint"
        }
      }
    },
    "tokens": {
      "viz.mark.bar.fill.default": "var(--cmp-viz-mark-bar-fill)",
      "viz.mark.bar.stroke.default": "var(--cmp-viz-mark-bar-stroke)",
      "viz.mark.bar.spacing": "var(--cmp-viz-mark-spacing)"
    },
    "dependencies": [
      "EncodingPositionX",
      "EncodingPositionY"
    ],
    "metadata": {
      "created": "2025-11-15",
      "updated": "2026-02-28",
      "owners": [
        "Viz team",
        "Design team"
      ],
      "maturity": "alpha",
      "conflicts_with": [
        "MarkLine",
        "MarkPoint",
        "MarkArea"
      ],
      "accessibility": {
        "rule_reference": "A11Y-R-04",
        "notes": "Requires redundant text/table fallback in paired specs."
      },
      "regionsUsed": [
        "detail",
        "dashboard",
        "form",
        "list"
      ],
      "examples": [
        "RevenueByRegion",
        "TicketVolumeByQueue"
      ],
      "references": [
        "RDS.7 Trait-Driven Visualization System Specification (v0.1)"
      ]
    },
    "objects": [
      "Invoice",
      "Subscription"
    ],
    "source": "traits/viz/mark-bar.trait.yaml"
  },
  "MarkGraph": {
    "name": "MarkGraph",
    "version": "0.1.1",
    "description": "Read-only force graph over a declared neighborhood edge array, rendered by public viz_render.",
    "category": "viz.mark",
    "tags": [
      "viz",
      "mark",
      "graph",
      "relationship"
    ],
    "contexts": [
      "detail"
    ],
    "viewExtensions": [
      {
        "component": "VizGraphPreview",
        "context": "detail",
        "position": "top",
        "priority": 60,
        "props": {
          "svgParameter": "previewSvg"
        }
      }
    ],
    "parameters": [
      {
        "name": "chart",
        "type": "object",
        "required": false,
        "description": "Declared edge-array chart source for the host object's neighborhood."
      },
      {
        "name": "title",
        "type": "string",
        "required": false,
        "description": "Title for the chart and its accessible figure."
      },
      {
        "name": "description",
        "type": "string",
        "required": false,
        "description": "Accessible description including the provenance of example edges."
      },
      {
        "name": "previewSvg",
        "type": "string",
        "required": false,
        "description": "Static SVG returned by public viz_render."
      }
    ],
    "schema": {
      "viz_mark_type": {
        "type": "string",
        "required": true,
        "default": "graph",
        "description": "Normalized graph mark identifier.",
        "validation": {
          "enum": [
            "graph"
          ]
        }
      }
    },
    "semantics": {},
    "tokens": {},
    "dependencies": [],
    "metadata": {
      "created": "2026-09-14",
      "updated": "2026-09-14",
      "owners": [
        "Viz team"
      ],
      "maturity": "alpha",
      "regionsUsed": [
        "detail"
      ],
      "accessibility": {
        "notes": "The wrapper names the static graph; node identifiers and the description remain available without color or interaction."
      }
    },
    "objects": [
      "Relationship"
    ],
    "source": "traits/viz/mark-graph.trait.yaml"
  },
  "MarkLine": {
    "name": "MarkLine",
    "version": "0.2.1",
    "description": "Canonical line mark for trends, rates, and progressions. Encodes values as\nconnected segments with configurable curve smoothing and join policies.",
    "category": "viz.mark",
    "tags": [
      "viz",
      "mark",
      "line",
      "trend"
    ],
    "contexts": [
      "dashboard",
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "VizLinePreview",
        "context": "detail",
        "position": "top",
        "priority": 60,
        "props": {
          "svgParameter": "previewSvg",
          "curveField": "viz_line_curve",
          "strokeWidthField": "viz_line_stroke_width",
          "markersField": "viz_line_markers"
        }
      },
      {
        "component": "VizLinePreview",
        "context": "dashboard",
        "position": "top",
        "priority": 60,
        "props": {
          "svgParameter": "previewSvg",
          "curveField": "viz_line_curve",
          "strokeWidthField": "viz_line_stroke_width",
          "markersField": "viz_line_markers"
        }
      },
      {
        "component": "VizLineControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "curveField": "viz_line_curve",
          "strokeField": "viz_line_stroke_width",
          "joinField": "viz_line_join",
          "markersField": "viz_line_markers"
        }
      },
      {
        "component": "VizRoleBadge",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "labelField": "viz_mark_role"
        }
      }
    ],
    "parameters": [
      {
        "name": "chart",
        "type": "object",
        "required": false,
        "description": "Optional read-only chart declaration binding existing domain fields; projects into supported detail and dashboard views."
      },
      {
        "name": "title",
        "type": "string",
        "required": false,
        "description": "Title for the bound chart and its accessible figure."
      },
      {
        "name": "description",
        "type": "string",
        "required": false,
        "description": "Description of the bound chart measurements and units."
      },
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment for the governed authoring recipes. Data rows remain a consumer operand."
      },
      {
        "name": "previewSvg",
        "type": "string",
        "required": false,
        "description": "Static SVG returned by viz_render for the authored sample; omitted until a chart is rendered."
      },
      {
        "name": "curve",
        "type": "string",
        "required": false,
        "description": "Curve interpolation strategy applied between data points.",
        "default": "linear",
        "validation": {
          "enum": [
            "linear",
            "monotone",
            "step"
          ]
        }
      },
      {
        "name": "strokeWidth",
        "type": "number",
        "required": false,
        "description": "Stroke width in device-independent pixels.",
        "default": 2,
        "validation": {
          "minimum": 1,
          "maximum": 8
        }
      },
      {
        "name": "join",
        "type": "string",
        "required": false,
        "description": "Join style applied when segments meet.",
        "default": "round",
        "validation": {
          "enum": [
            "miter",
            "round",
            "bevel"
          ]
        }
      },
      {
        "name": "enableMarkers",
        "type": "boolean",
        "required": false,
        "description": "Adds optional point markers on line vertices.",
        "default": false
      }
    ],
    "schema": {
      "viz_mark_type": {
        "type": "string",
        "required": true,
        "description": "Normalized mark identifier consumed by renderer adapters.",
        "default": "line",
        "validation": {
          "enum": [
            "line"
          ]
        }
      },
      "viz_line_curve": {
        "type": "string",
        "required": false,
        "description": "Curve interpolation strategy derived from parameters.",
        "defaultFromParameter": "curve",
        "validation": {
          "enum": [
            "linear",
            "monotone",
            "step"
          ]
        }
      },
      "viz_line_stroke_width": {
        "type": "number",
        "required": false,
        "description": "Stroke width in pixels.",
        "defaultFromParameter": "strokeWidth",
        "validation": {
          "minimum": 1,
          "maximum": 8
        }
      },
      "viz_line_join": {
        "type": "string",
        "required": false,
        "description": "Join style used for connecting segments.",
        "defaultFromParameter": "join",
        "validation": {
          "enum": [
            "miter",
            "round",
            "bevel"
          ]
        }
      },
      "viz_line_markers": {
        "type": "boolean",
        "required": false,
        "description": "Indicates whether point markers render along the series.",
        "defaultFromParameter": "enableMarkers"
      },
      "viz_mark_role": {
        "type": "string",
        "required": true,
        "description": "Semantic role used for heuristics and docs.",
        "default": "trend"
      },
      "viz_mark_a11y_label": {
        "type": "string",
        "required": true,
        "description": "Accessible description fragment for describing the line mark.",
        "default": "Line mark showing change over time or ordered categories."
      }
    },
    "semantics": {
      "viz_mark_type": {
        "semantic_type": "viz.mark.type",
        "token_mapping": "tokenMap(viz.mark.type)",
        "ui_hints": {
          "component": "VizMarkSummary"
        }
      },
      "viz_line_curve": {
        "semantic_type": "viz.mark.curve",
        "token_mapping": "tokenMap(viz.mark.curve)",
        "ui_hints": {
          "component": "VizCurveHint"
        }
      },
      "viz_line_stroke_width": {
        "semantic_type": "viz.mark.stroke_width",
        "token_mapping": "tokenMap(viz.mark.stroke_width)",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "px"
        }
      },
      "viz_line_join": {
        "semantic_type": "viz.mark.join",
        "token_mapping": "tokenMap(viz.mark.join)",
        "ui_hints": {
          "component": "TextBadge"
        }
      },
      "viz_line_markers": {
        "semantic_type": "viz.mark.markers",
        "token_mapping": "tokenMap(viz.mark.marker)",
        "ui_hints": {
          "component": "BooleanBadge"
        }
      },
      "viz_mark_a11y_label": {
        "semantic_type": "a11y.description",
        "token_mapping": "tokenMap(a11y.chart.description)",
        "ui_hints": {
          "component": "ScreenReaderHint"
        }
      }
    },
    "tokens": {
      "viz.mark.line.stroke.default": "var(--cmp-viz-mark-line-stroke)",
      "viz.mark.line.stroke.highlight": "var(--cmp-viz-mark-line-highlight)",
      "viz.mark.line.marker.fill": "var(--cmp-viz-mark-point-fill)"
    },
    "dependencies": [
      "EncodingPositionX",
      "EncodingPositionY"
    ],
    "metadata": {
      "created": "2025-11-15",
      "updated": "2026-02-28",
      "owners": [
        "Viz team",
        "Design team"
      ],
      "maturity": "alpha",
      "conflicts_with": [
        "MarkBar",
        "MarkPoint",
        "MarkArea"
      ],
      "accessibility": {
        "rule_reference": "A11Y-R-05",
        "notes": "Provide textual summary for trend direction and extrema."
      },
      "regionsUsed": [
        "detail",
        "dashboard",
        "form",
        "list"
      ],
      "examples": [
        "ActiveUsersTrend",
        "ConversionRateTimeline"
      ],
      "references": [
        "RDS.7 Trait-Driven Visualization System Specification (v0.1)"
      ]
    },
    "objects": [
      "Usage"
    ],
    "source": "traits/viz/mark-line.trait.yaml"
  },
  "MarkPoint": {
    "name": "MarkPoint",
    "version": "0.2.1",
    "description": "Canonical point mark for scatterplots and overlays. Encodes each datum as a\ndiscrete glyph with configurable shape, size, and fill semantics.",
    "category": "viz.mark",
    "tags": [
      "viz",
      "mark",
      "point",
      "distribution"
    ],
    "contexts": [
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "VizPointPreview",
        "context": "detail",
        "position": "top",
        "priority": 55,
        "props": {
          "svgParameter": "previewSvg",
          "shapeField": "viz_point_shape",
          "sizeField": "viz_point_size",
          "fillField": "viz_point_fill"
        }
      },
      {
        "component": "VizPointControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "shapeField": "viz_point_shape",
          "sizeField": "viz_point_size",
          "opacityField": "viz_point_opacity",
          "strokeField": "viz_point_stroke_width"
        }
      },
      {
        "component": "VizRoleBadge",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "labelField": "viz_mark_role"
        }
      }
    ],
    "parameters": [
      {
        "name": "chart",
        "type": "object",
        "required": false,
        "description": "Optional read-only chart declaration binding existing domain fields; projects into supported detail and dashboard views."
      },
      {
        "name": "title",
        "type": "string",
        "required": false,
        "description": "Title for the bound chart and its accessible figure."
      },
      {
        "name": "description",
        "type": "string",
        "required": false,
        "description": "Description of the bound chart measurements and units."
      },
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment for the governed authoring recipes. Data rows remain a consumer operand."
      },
      {
        "name": "previewSvg",
        "type": "string",
        "required": false,
        "description": "Static SVG returned by viz_render for the authored sample; omitted until a chart is rendered."
      },
      {
        "name": "shape",
        "type": "string",
        "required": false,
        "description": "Glyph shape rendered for each data point.",
        "default": "circle",
        "validation": {
          "enum": [
            "circle",
            "square",
            "diamond",
            "triangle"
          ]
        }
      },
      {
        "name": "size",
        "type": "number",
        "required": false,
        "description": "Default glyph area in square pixels.",
        "default": 48,
        "validation": {
          "minimum": 4,
          "maximum": 196
        }
      },
      {
        "name": "fill",
        "type": "string",
        "required": false,
        "description": "Fill strategy for glyph interior.",
        "default": "solid",
        "validation": {
          "enum": [
            "solid",
            "hollow"
          ]
        }
      },
      {
        "name": "strokeWidth",
        "type": "number",
        "required": false,
        "description": "Outline stroke width for hollow glyphs.",
        "default": 1,
        "validation": {
          "minimum": 0,
          "maximum": 6
        }
      },
      {
        "name": "opacity",
        "type": "number",
        "required": false,
        "description": "Default opacity applied to each point for overplotting.",
        "default": 0.85,
        "validation": {
          "minimum": 0.1,
          "maximum": 1
        }
      }
    ],
    "schema": {
      "viz_mark_type": {
        "type": "string",
        "required": true,
        "description": "Normalized mark identifier consumed by renderer adapters.",
        "default": "point",
        "validation": {
          "enum": [
            "point"
          ]
        }
      },
      "viz_point_shape": {
        "type": "string",
        "required": false,
        "description": "Glyph shape applied to all rendered points by default.",
        "defaultFromParameter": "shape",
        "validation": {
          "enum": [
            "circle",
            "square",
            "diamond",
            "triangle"
          ]
        }
      },
      "viz_point_size": {
        "type": "number",
        "required": false,
        "description": "Default glyph area in square pixels.",
        "defaultFromParameter": "size",
        "validation": {
          "minimum": 4,
          "maximum": 196
        }
      },
      "viz_point_fill": {
        "type": "string",
        "required": false,
        "description": "Fill strategy for glyph interior.",
        "defaultFromParameter": "fill",
        "validation": {
          "enum": [
            "solid",
            "hollow"
          ]
        }
      },
      "viz_point_stroke_width": {
        "type": "number",
        "required": false,
        "description": "Outline stroke width for hollow glyphs.",
        "defaultFromParameter": "strokeWidth",
        "validation": {
          "minimum": 0,
          "maximum": 6
        }
      },
      "viz_point_opacity": {
        "type": "number",
        "required": false,
        "description": "Default opacity used for overplotting mitigation.",
        "defaultFromParameter": "opacity",
        "validation": {
          "minimum": 0.1,
          "maximum": 1
        }
      },
      "viz_mark_role": {
        "type": "string",
        "required": true,
        "description": "Semantic role for heuristics and docs.",
        "default": "distribution"
      },
      "viz_mark_a11y_label": {
        "type": "string",
        "required": true,
        "description": "Accessible description fragment for describing point marks.",
        "default": "Point mark representing discrete values or observations."
      }
    },
    "semantics": {
      "viz_mark_type": {
        "semantic_type": "viz.mark.type",
        "token_mapping": "tokenMap(viz.mark.type)",
        "ui_hints": {
          "component": "VizMarkSummary"
        }
      },
      "viz_point_shape": {
        "semantic_type": "viz.mark.shape",
        "token_mapping": "tokenMap(viz.mark.shape)",
        "ui_hints": {
          "component": "VizShapeHint"
        }
      },
      "viz_point_size": {
        "semantic_type": "viz.mark.size",
        "token_mapping": "tokenMap(viz.mark.size)",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "px^2"
        }
      },
      "viz_point_fill": {
        "semantic_type": "viz.mark.fill",
        "token_mapping": "tokenMap(viz.mark.fill)",
        "ui_hints": {
          "component": "TextBadge"
        }
      },
      "viz_point_opacity": {
        "semantic_type": "viz.mark.opacity",
        "token_mapping": "tokenMap(viz.mark.opacity)",
        "ui_hints": {
          "component": "NumericPreview",
          "unit": "opacity"
        }
      },
      "viz_mark_a11y_label": {
        "semantic_type": "a11y.description",
        "token_mapping": "tokenMap(a11y.chart.description)",
        "ui_hints": {
          "component": "ScreenReaderHint"
        }
      }
    },
    "tokens": {
      "viz.mark.point.fill.default": "var(--cmp-viz-mark-point-fill)",
      "viz.mark.point.stroke.default": "var(--cmp-viz-mark-point-stroke)",
      "viz.mark.point.opacity.default": "var(--cmp-viz-mark-point-opacity)"
    },
    "dependencies": [
      "EncodingPositionX",
      "EncodingPositionY"
    ],
    "metadata": {
      "created": "2025-11-15",
      "updated": "2026-02-28",
      "owners": [
        "Viz team",
        "Design team"
      ],
      "maturity": "alpha",
      "conflicts_with": [
        "MarkBar",
        "MarkLine",
        "MarkArea"
      ],
      "accessibility": {
        "rule_reference": "A11Y-R-01",
        "notes": "Provide redundant encoding (color, shape, or texture) per RDV.4."
      },
      "regionsUsed": [
        "detail",
        "form",
        "list"
      ],
      "examples": [
        "ProfitVsRevenue",
        "SLAHeatScatter"
      ],
      "references": [
        "RDS.7 Trait-Driven Visualization System Specification (v0.1)"
      ]
    },
    "objects": [],
    "source": "traits/viz/mark-point.trait.yaml"
  },
  "MarkRect": {
    "name": "MarkRect",
    "version": "0.1.1",
    "description": "Heatmap authoring over the existing MarkRect renderer",
    "category": "viz.mark",
    "tags": [
      "viz",
      "authoring"
    ],
    "contexts": [
      "detail",
      "form"
    ],
    "viewExtensions": [
      {
        "component": "VizHeatmapControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent"
        }
      },
      {
        "component": "VizHeatmapPreview",
        "context": "detail",
        "position": "top",
        "priority": null,
        "props": {
          "svgParameter": "previewSvg"
        }
      }
    ],
    "parameters": [
      {
        "name": "chart",
        "type": "object",
        "required": false,
        "description": "Optional read-only chart declaration binding existing domain fields; projects into supported detail and dashboard views."
      },
      {
        "name": "title",
        "type": "string",
        "required": false,
        "description": "Title for the bound chart and its accessible figure."
      },
      {
        "name": "description",
        "type": "string",
        "required": false,
        "description": "Description of the bound chart measurements and units."
      },
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment; data rows are supplied by the consumer."
      },
      {
        "name": "previewSvg",
        "type": "string",
        "required": false,
        "description": "Static SVG returned by viz_render for the authored sample."
      }
    ],
    "schema": {},
    "semantics": {},
    "tokens": {},
    "dependencies": [],
    "metadata": {
      "regionsUsed": [
        "form",
        "detail"
      ]
    },
    "objects": [],
    "source": "traits/viz/mark-rect.trait.yaml"
  },
  "Ownerable": {
    "name": "Ownerable",
    "version": "1.0.0",
    "description": "Adds ownership metadata linking entities to their governing account or principal with transfer auditing.",
    "category": "structural",
    "tags": [
      "ownership",
      "governance",
      "relationships",
      "access"
    ],
    "contexts": [
      "card",
      "detail",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "OwnershipSummary",
        "context": "detail",
        "position": "top",
        "priority": null,
        "props": {
          "ownerIdField": "owner_id",
          "ownerTypeField": "owner_type",
          "roleField": "ownership_role",
          "transferredAtField": "ownership_transferred_at",
          "allowTransferParameter": "allowTransfer"
        }
      },
      {
        "component": "OwnerBadge",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "ownerIdField": "owner_id",
          "ownerTypeField": "owner_type"
        }
      },
      {
        "component": "OwnershipMeta",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "ownerIdField": "owner_id",
          "ownerTypeField": "owner_type",
          "roleField": "ownership_role"
        }
      }
    ],
    "parameters": [
      {
        "name": "ownerTypes",
        "type": "string[]",
        "required": true,
        "description": "Allow list of principals permitted to own the entity.",
        "default": [
          "organization",
          "team",
          "user"
        ]
      },
      {
        "name": "primaryOwnerType",
        "type": "string",
        "required": false,
        "description": "Default owner type applied when authoring new records.",
        "default": "organization",
        "validation": {
          "enumFromParameter": "ownerTypes"
        }
      },
      {
        "name": "allowTransfer",
        "type": "boolean",
        "required": false,
        "description": "Whether ownership may be reassigned after initial creation.",
        "default": true
      }
    ],
    "schema": {
      "owner_id": {
        "type": "string",
        "required": true,
        "description": "Identifier of the owning principal scoped by owner_type."
      },
      "owner_type": {
        "type": "string",
        "required": true,
        "description": "Categorical owner type sourced from the ownerTypes parameter.",
        "validation": {
          "enumFromParameter": "ownerTypes"
        }
      },
      "ownership_role": {
        "type": "string",
        "required": false,
        "description": "Optional role name describing how the owner governs the entity.",
        "validation": {
          "maxLength": 80
        }
      },
      "ownership_transferred_at": {
        "type": "datetime",
        "required": false,
        "description": "Timestamp recording when ownership was last transferred."
      }
    },
    "semantics": {
      "owner_id": {
        "semantic_type": "ownership.owner.id",
        "token_mapping": "tokenMap(ownership.owner.id)",
        "ui_hints": {
          "component": "OwnerReference",
          "ownerTypeField": "owner_type"
        }
      },
      "owner_type": {
        "semantic_type": "ownership.owner.type",
        "token_mapping": "tokenMap(ownership.owner.type)",
        "ui_hints": {
          "component": "OwnerTypeBadge",
          "parameterSource": "ownerTypes"
        }
      },
      "ownership_role": {
        "semantic_type": "ownership.owner.role",
        "token_mapping": "tokenMap(ownership.owner.role)",
        "ui_hints": {
          "component": "OwnerRolePill"
        }
      },
      "ownership_transferred_at": {
        "semantic_type": "ownership.owner.transferred_at",
        "token_mapping": "tokenMap(ownership.owner.timestamp)",
        "ui_hints": {
          "component": "TimelineTimestamp"
        }
      }
    },
    "tokens": {
      "ownership.owner.badge.bg": "var(--surface-subtle)",
      "ownership.owner.badge.text": "var(--text-default)",
      "ownership.owner.role.text": "var(--text-muted)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-10-16",
      "owners": [
        "Governance team",
        "Platform team"
      ],
      "maturity": "stable",
      "accessibility": {
        "keyboard": "n/a",
        "screenreader": "Announces owning principal, type, and transfer state."
      },
      "regionsUsed": [
        "detail",
        "list",
        "card"
      ],
      "examples": [
        "Project",
        "Workspace"
      ],
      "references": [
        "Trait Engine Spec v0.1 §2"
      ]
    },
    "objects": [
      "Agent",
      "Closure",
      "Grant",
      "Organization",
      "Plan",
      "Relationship",
      "Task"
    ],
    "source": "traits/structural/Ownerable.trait.yaml"
  },
  "Pageable": {
    "name": "Pageable",
    "version": "1.0.0",
    "description": "Adds pagination controls to list and collection views. Pageable injects a pagination bar\ninto the footer region, wires page state to the data layer, and provides semantic token\nmappings for consistent pagination UI styling across brands.\n\nThe trait supports configurable page sizes, total item counts for page calculation,\nand both simple (prev/next) and full (goto page) navigation modes. Page state is managed\nvia the page and pageSize props, which the consuming layout binds to data offset/limit\nparameters or API pagination cursors.",
    "category": "behavioral",
    "tags": [
      "pagination",
      "list-behavior",
      "navigation",
      "data-loading"
    ],
    "contexts": [
      "list"
    ],
    "viewExtensions": [
      {
        "component": "PaginationBar",
        "context": "list",
        "position": "footer",
        "priority": 10,
        "props": {
          "pageField": "page",
          "pageSizeField": "pageSize",
          "totalItemsField": "totalItems",
          "totalPagesField": "totalPages",
          "pageSizeOptionsParameter": "pageSizeOptions",
          "showPageSizeSelectorParameter": "showPageSizeSelector",
          "showGotoPageParameter": "showGotoPage",
          "showItemRangeParameter": "showItemRange"
        }
      }
    ],
    "parameters": [
      {
        "name": "defaultPageSize",
        "type": "number",
        "required": false,
        "description": "Default number of items per page.",
        "default": 25,
        "validation": {
          "minimum": 1,
          "maximum": 500
        }
      },
      {
        "name": "pageSizeOptions",
        "type": "number[]",
        "required": false,
        "description": "Available page size choices for the user. Displayed as a dropdown in the pagination bar.\nMust be sorted ascending.\n",
        "default": [
          10,
          25,
          50,
          100
        ],
        "validation": {
          "minItems": 1,
          "uniqueItems": true
        }
      },
      {
        "name": "showPageSizeSelector",
        "type": "boolean",
        "required": false,
        "description": "Whether to display the page size dropdown selector.",
        "default": true
      },
      {
        "name": "showGotoPage",
        "type": "boolean",
        "required": false,
        "description": "Whether to display a \"go to page\" input for direct page navigation.",
        "default": false
      },
      {
        "name": "showItemRange",
        "type": "boolean",
        "required": false,
        "description": "Whether to display the item range indicator (e.g., \"Showing 26-50 of 312\").\n",
        "default": true
      }
    ],
    "schema": {
      "page": {
        "type": "number",
        "required": true,
        "description": "Current page number (1-based).",
        "default": 1,
        "validation": {
          "minimum": 1
        }
      },
      "pageSize": {
        "type": "number",
        "required": true,
        "description": "Number of items displayed per page.",
        "default": 25,
        "validation": {
          "minimum": 1,
          "maximum": 500
        }
      },
      "totalItems": {
        "type": "number",
        "required": false,
        "description": "Total number of items across all pages. Used to compute total page count.",
        "default": 0,
        "validation": {
          "minimum": 0
        }
      },
      "totalPages": {
        "type": "number",
        "required": false,
        "description": "Computed total number of pages (ceil(totalItems / pageSize)).",
        "default": 0,
        "validation": {
          "minimum": 0
        }
      }
    },
    "semantics": {
      "page": {
        "semantic_type": "state.pagination.page",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "PaginationBar",
          "description": "Current active page, drives page button highlight state."
        }
      },
      "pageSize": {
        "semantic_type": "state.pagination.pageSize",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "PaginationBar",
          "defaultParameter": "defaultPageSize"
        }
      },
      "totalItems": {
        "semantic_type": "metric.pagination.totalItems",
        "token_mapping": "tokenMap(pagination.info.*)",
        "ui_hints": {
          "component": "PaginationBar",
          "format": "integer"
        }
      },
      "totalPages": {
        "semantic_type": "metric.pagination.totalPages",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "PaginationBar",
          "description": "Computed from totalItems and pageSize."
        }
      }
    },
    "tokens": {
      "pagination.bar.bg": "var(--sys-surface-secondary)",
      "pagination.bar.border": "var(--sys-border-default)",
      "pagination.button.bg": "var(--sys-surface-default)",
      "pagination.button.text": "var(--sys-text-primary)",
      "pagination.button.hover.bg": "var(--sys-surface-hover)",
      "pagination.button.active.bg": "var(--sys-surface-accent)",
      "pagination.button.active.text": "var(--sys-text-on-accent)",
      "pagination.button.disabled.text": "var(--sys-text-disabled)",
      "pagination.info.text": "var(--sys-text-subtle)",
      "pagination.selector.border": "var(--sys-border-default)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2026-03-05",
      "updated": "2026-03-05",
      "owners": [
        "Design team"
      ],
      "maturity": "stable",
      "accessibility": {
        "keyboard": "PaginationBar supports full keyboard navigation:\n- Tab to move between page buttons, page size selector, and goto input\n- Enter/Space to activate a page button\n- Arrow keys to increment/decrement page in goto input\n- Home/End to jump to first/last page\n",
        "screenreader": "Pagination bar uses nav role with aria-label=\"Pagination\".\nCurrent page announced via aria-current=\"page\".\nPage buttons announce their page number.\nItem range indicator reads \"Showing X to Y of Z items\".\nDisabled prev/next buttons announce as disabled.\n"
      },
      "regionsUsed": [
        "list"
      ],
      "examples": [
        "Product catalog pagination",
        "User directory pagination",
        "Invoice list pagination"
      ],
      "references": [
        "Trait Engine Spec v0.1 section 2"
      ]
    },
    "objects": [
      "Product"
    ],
    "source": "traits/behavioral/Pageable.trait.yaml"
  },
  "Preferenceable": {
    "name": "Preferenceable",
    "version": "1.0.0",
    "description": "User preference trait backed by JSONB storage, schema versioning, and registry governance. Encodes namespaces such as theme, notifications, and display with deterministic overrides.",
    "category": "core",
    "tags": [
      "preferences",
      "jsonb",
      "schema-evolution",
      "user-settings",
      "notification"
    ],
    "contexts": [
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "PreferenceSummaryBadge",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "namespacesField": "preference_namespaces",
          "versionField": "preference_version"
        }
      },
      {
        "component": "PreferencePanel",
        "context": "detail",
        "position": "main",
        "priority": 55,
        "props": {
          "preferencesField": "preference_document",
          "metadataField": "preference_metadata",
          "namespaceField": "preference_namespaces"
        }
      },
      {
        "component": "PreferenceEditor",
        "context": "form",
        "position": "main",
        "priority": null,
        "props": {
          "namespacesField": "preference_namespaces",
          "documentField": "preference_document",
          "registryNamespaceParameter": "registryNamespace"
        }
      }
    ],
    "parameters": [
      {
        "name": "namespaces",
        "type": "string[]",
        "required": true,
        "description": "Allowed top-level namespaces for preference keys (theme, notifications, display, etc.).",
        "default": [
          "theme",
          "notifications",
          "display"
        ],
        "validation": {
          "minItems": 1,
          "maxItems": 12,
          "uniqueItems": true,
          "items": {
            "pattern": "^[a-z0-9._-]+$",
            "minLength": 2,
            "maxLength": 48
          }
        }
      },
      {
        "name": "schemaVersion",
        "type": "string",
        "required": true,
        "description": "Current JSON Schema version served by the registry for validation and UI generation.",
        "default": "1.0.0",
        "validation": {
          "pattern": "^\\d+\\.\\d+\\.\\d+$"
        }
      },
      {
        "name": "allowUnknownNamespaces",
        "type": "boolean",
        "required": false,
        "description": "Escape hatch allowing writes outside the declared namespace allow list.",
        "default": false
      },
      {
        "name": "registryNamespace",
        "type": "string",
        "required": false,
        "description": "Registry identifier used to fetch JSON Schema and uiSchema bundles.",
        "default": "user-preferences",
        "validation": {
          "pattern": "^[a-z0-9._-]+$"
        }
      }
    ],
    "schema": {
      "preference_document": {
        "type": "PreferenceDocument",
        "required": true,
        "description": "Normalized preference payload captured by PreferenceStore (version, preferences map, metadata).",
        "default": {
          "version": "1.0.0",
          "preferences": {
            "theme": {
              "mode": "system"
            },
            "notifications": {
              "mention": {
                "email": true,
                "push": true
              }
            }
          },
          "metadata": {
            "schemaVersion": "1.0.0",
            "lastUpdated": "2025-11-18T00:00:00Z",
            "source": "system",
            "migrationApplied": []
          }
        }
      },
      "preference_metadata": {
        "type": "PreferenceMetadata",
        "required": true,
        "description": "Tracks schema version, lastUpdated timestamp, migration records, and source."
      },
      "preference_version": {
        "defaultFromParameter": "schemaVersion",
        "type": "string",
        "required": true,
        "description": "SemVer mirror of preference_document.version for indexing and analytics.",
        "validation": {
          "pattern": "^\\d+\\.\\d+\\.\\d+$"
        }
      },
      "preference_namespaces": {
        "defaultFromParameter": "namespaces",
        "type": "string[]",
        "required": true,
        "description": "Materialized namespace list resolved from parameters/registry for auditing.",
        "default": [
          "theme",
          "notifications",
          "display"
        ]
      },
      "preference_mutations": {
        "type": "number",
        "required": false,
        "description": "Monotonic counter incremented whenever preferences mutate (invalidates caches).",
        "default": 0,
        "validation": {
          "minimum": 0
        }
      }
    },
    "semantics": {
      "preference_document": {
        "semantic_type": "preferences.document",
        "token_mapping": "tokenMap(preferences.document)",
        "ui_hints": {
          "component": "PreferenceDiffPanel",
          "registryNamespaceParameter": "registryNamespace"
        }
      },
      "preference_metadata": {
        "semantic_type": "preferences.metadata",
        "token_mapping": "tokenMap(preferences.metadata)",
        "ui_hints": {
          "component": "PreferenceDiagnostics"
        }
      },
      "preference_version": {
        "semantic_type": "preferences.version",
        "token_mapping": "tokenMap(preferences.version)",
        "ui_hints": {
          "component": "PreferenceVersionBadge"
        }
      },
      "preference_namespaces": {
        "semantic_type": "preferences.namespaces",
        "token_mapping": "tokenMap(preferences.namespaces)",
        "ui_hints": {
          "component": "PreferenceNamespaceChips"
        }
      }
    },
    "tokens": {
      "preferences.panel.bg": "var(--sys-surface-raised)",
      "preferences.panel.border": "var(--sys-border-strong)",
      "preferences.namespace.badge.bg": "var(--sys-surface-muted)",
      "preferences.namespace.badge.text": "var(--sys-text-strong)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-18",
      "owners": [
        "Core team",
        "Platform team"
      ],
      "maturity": "experimental",
      "accessibility": {
        "keyboard": "PreferenceEditor supports namespace-by-namespace keyboard traversal with aria landmarks.",
        "screenreader": "PreferencePanel announces namespace and control labels derived from JSON Schema titles."
      },
      "regionsUsed": [
        "list",
        "detail",
        "form"
      ],
      "examples": [
        "User",
        "Subscription"
      ],
      "references": [
        "R21.5 Preferenceable Trait Implementation",
        "objects/provenance.v1.json#/references/ref-2181d6411382"
      ]
    },
    "objects": [
      "Organization",
      "User"
    ],
    "source": "traits/core/Preferenceable.trait.yaml"
  },
  "Priceable": {
    "name": "Priceable",
    "version": "1.0.0",
    "description": "Introduces monetization metadata with currency handling, pricing models, and billing cadence semantics.",
    "category": "financial",
    "tags": [
      "pricing",
      "monetization",
      "commerce",
      "billing"
    ],
    "contexts": [
      "card",
      "detail",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "PriceSummary",
        "context": "detail",
        "position": "top",
        "priority": null,
        "props": {
          "amountField": "unit_amount_cents",
          "currencyField": "currency",
          "modelField": "pricing_model",
          "intervalField": "billing_interval",
          "taxBehaviorField": "tax_behavior"
        }
      },
      {
        "component": "PriceBadge",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "amountField": "unit_amount_cents",
          "currencyField": "currency"
        }
      },
      {
        "component": "PriceBadge",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "amountField": "unit_amount_cents",
          "currencyField": "currency"
        }
      }
    ],
    "parameters": [
      {
        "name": "supportedCurrencies",
        "type": "string[]",
        "required": true,
        "description": "ISO currency codes permitted for pricing this entity.",
        "default": [
          "USD",
          "EUR",
          "GBP"
        ]
      },
      {
        "name": "defaultCurrency",
        "type": "string",
        "required": false,
        "description": "Currency preselected when authoring pricing information.",
        "default": "USD",
        "validation": {
          "enumFromParameter": "supportedCurrencies"
        }
      },
      {
        "name": "pricingModels",
        "type": "string[]",
        "required": true,
        "description": "Supported strategies describing how the entity is monetized.",
        "default": [
          "one_time",
          "subscription",
          "usage_based"
        ]
      },
      {
        "name": "billingIntervals",
        "type": "string[]",
        "required": false,
        "description": "Allowed billing cadences when the pricing model is subscription based.",
        "default": [
          "one_time",
          "day",
          "week",
          "month",
          "year"
        ]
      },
      {
        "name": "taxBehavior",
        "type": "string",
        "required": false,
        "description": "Indicates whether prices are tax inclusive or exclusive.",
        "default": "exclusive",
        "validation": {
          "enum": [
            "exclusive",
            "inclusive"
          ]
        }
      }
    ],
    "schema": {
      "unit_amount_cents": {
        "type": "number",
        "required": true,
        "description": "Base unit price expressed in the smallest currency denomination.",
        "validation": {
          "minimum": 0
        }
      },
      "currency": {
        "type": "string",
        "required": true,
        "description": "ISO currency code for the unit amount.",
        "validation": {
          "enumFromParameter": "supportedCurrencies"
        }
      },
      "pricing_model": {
        "type": "string",
        "required": true,
        "description": "Monetization model applied to the entity.",
        "validation": {
          "enumFromParameter": "pricingModels"
        }
      },
      "billing_interval": {
        "type": "string",
        "required": false,
        "description": "Billing cadence when pricing_model indicates recurring revenue.",
        "validation": {
          "enumFromParameter": "billingIntervals"
        }
      },
      "tax_behavior": {
        "type": "string",
        "required": true,
        "description": "Defines whether taxes are included in the displayed price.",
        "validation": {
          "enum": [
            "exclusive",
            "inclusive"
          ]
        },
        "default": "exclusive"
      }
    },
    "semantics": {
      "unit_amount_cents": {
        "semantic_type": "commerce.price.amount",
        "token_mapping": "tokenMap(commerce.price.primary)",
        "ui_hints": {
          "minorUnits": 100,
          "component": "CurrencyAmount",
          "currencyField": "currency"
        }
      },
      "currency": {
        "semantic_type": "commerce.price.currency",
        "token_mapping": "tokenMap(commerce.currency.primary)",
        "ui_hints": {
          "component": "CurrencyCode",
          "parameterSource": "supportedCurrencies"
        }
      },
      "pricing_model": {
        "semantic_type": "commerce.price.model",
        "token_mapping": "tokenMap(commerce.pricing.model)",
        "ui_hints": {
          "component": "PricingModelBadge",
          "parameterSource": "pricingModels"
        }
      },
      "billing_interval": {
        "semantic_type": "commerce.price.interval",
        "token_mapping": "tokenMap(commerce.pricing.interval)",
        "ui_hints": {
          "component": "BillingIntervalBadge",
          "parameterSource": "billingIntervals"
        }
      },
      "tax_behavior": {
        "semantic_type": "commerce.price.tax_behavior",
        "token_mapping": "tokenMap(commerce.pricing.tax)",
        "ui_hints": {
          "component": "TaxBehaviorTag"
        }
      }
    },
    "tokens": {
      "commerce.price.text": "var(--text-strong)",
      "commerce.price.badge.bg": "var(--surface-accent)",
      "commerce.pricing.model.text": "var(--text-default)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-10-16",
      "owners": [
        "Commerce team",
        "Finance team"
      ],
      "maturity": "stable",
      "accessibility": {
        "keyboard": "n/a",
        "screenreader": "Announces price, currency, billing interval, and tax behavior."
      },
      "regionsUsed": [
        "detail",
        "list",
        "card"
      ],
      "examples": [
        "Product",
        "Subscription"
      ],
      "references": [
        "Trait Engine Spec v0.1 §2"
      ]
    },
    "objects": [
      "Product",
      "Transaction"
    ],
    "source": "traits/financial/Priceable.trait.yaml"
  },
  "Provenanced": {
    "name": "Provenanced",
    "version": "1.0.0",
    "description": "Carries how a record's values were obtained, beside the values, wherever the record travels.\n\nTwo values obtained differently are not comparable: a route an agent inferred from a URL and a route an\nOpenAPI document declares can hold the same string and mean different things, and a screen that shows\none beside the other unlabelled publishes a false equivalence. A captured finding is only as good as the\nengine, the version, the file and the moment behind it.\n\nOODS Foundry already carries this shape twice, and this trait is factored from them rather than inventing a\nthird. The observation rows name the capture run, the target, the artifact kind and read path, and the\ncapture time beside each row; the preview's context panel names each item's source, id, the query that\nfound it and when it was fetched. What both say is the same five things: which source, which record\nin it, where in that record, how, and when. Those are the five fields here:\n\n  provenance_source   who produced it            observation: the capture tool  context: source\n  provenance_record   which record there         observation: runId           context: id\n  provenance_locator  where in that record       observation: readPath        context: query\n  provenance_method   how the value was obtained  observation: artifactKind   context: (the search)\n  provenance_at       when                        observation: capturedAt      context: fetchedAt\n\nThe method is the field that separates this from a citation: \"axe-core 4.11.0\", \"route_derived\",\n\"openapi_declared\", \"sha256 attested by the run manifest\". The observation rows and context items keep\ntheir own stored shapes for now.\n\nAn absent value means not recorded, never \"no provenance needed\". A record with no provenance_source\nis not shown as sourced.",
    "category": "core",
    "tags": [
      "provenance",
      "evidence",
      "lineage",
      "citation"
    ],
    "contexts": [
      "card",
      "detail",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "Text",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "field": "provenance_method",
          "label": "Obtained by"
        }
      },
      {
        "component": "RelativeTimestamp",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "field": "provenance_at",
          "label": "Obtained"
        }
      },
      {
        "component": "RelativeTimestamp",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "field": "provenance_at"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 66,
        "props": {
          "field": "provenance_source",
          "label": "Source"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 65,
        "props": {
          "field": "provenance_method",
          "label": "Obtained by"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 64,
        "props": {
          "field": "provenance_locator",
          "label": "Read from"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 63,
        "props": {
          "field": "provenance_record",
          "label": "Record"
        }
      }
    ],
    "parameters": [
      {
        "name": "source",
        "type": "string",
        "required": true,
        "description": "The producing system every record of this object comes from, shown as recorded (e.g. a capture tool)."
      },
      {
        "name": "methodLabel",
        "type": "string",
        "required": false,
        "description": "Visible wording beside the method, so the screen says how rather than showing a bare token.",
        "default": "Obtained by"
      }
    ],
    "schema": {
      "provenance_source": {
        "type": "string",
        "required": true,
        "description": "The system that produced the record, such as a capture tool."
      },
      "provenance_record": {
        "type": "string",
        "required": true,
        "description": "Which record in that system — a run id, an item id."
      },
      "provenance_locator": {
        "type": "string",
        "required": false,
        "description": "Where in that record the value was read — a file path under the run, a query."
      },
      "provenance_method": {
        "type": "string",
        "required": true,
        "description": "How the value was obtained — the engine and its version, the inference, the declaration, the\nattestation. Two values with different methods are not presented as the same kind of fact.\n"
      },
      "provenance_at": {
        "type": "datetime",
        "required": true,
        "description": "When it was obtained.",
        "validation": {
          "format": "date-time"
        }
      }
    },
    "semantics": {
      "provenance_source": {
        "semantic_type": "provenance.source",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text"
        }
      },
      "provenance_record": {
        "semantic_type": "provenance.record",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text"
        }
      },
      "provenance_locator": {
        "semantic_type": "provenance.locator",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text"
        }
      },
      "provenance_method": {
        "semantic_type": "provenance.method",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "Text"
        }
      },
      "provenance_at": {
        "semantic_type": "provenance.at",
        "token_mapping": "tokenMap(text.body.*)",
        "ui_hints": {
          "component": "RelativeTimestamp"
        }
      }
    },
    "tokens": {},
    "dependencies": [],
    "metadata": {
      "created": "2026-09-18",
      "updated": "2026-09-18",
      "owners": [
        "Core team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "Provenance adds no interactive control; it renders as labelled text.",
        "screenreader": "Each value is read with its visible label (\"Obtained by axe-core 4.11.0\")."
      },
      "regionsUsed": [
        "list",
        "card",
        "detail"
      ],
      "examples": [
        "Finding",
        "Run",
        "CapturedArtifact"
      ],
      "references": [
        "objects/provenance.v1.json#/references/ref-55ab62519302 — observation rows: runId, target, artifactKind, readPath, capturedAt",
        "objects/provenance.v1.json#/references/ref-38c48888c8fe — context items: source, id, query, fetchedAt"
      ]
    },
    "objects": [],
    "source": "traits/core/Provenanced.trait.yaml"
  },
  "SaaSBillingBillable": {
    "name": "SaaSBillingBillable",
    "version": "1.0.0",
    "description": "Normalizes recurring price configuration for SaaS plans including cadence, currency, and trial policy. NOTE (trait-split gap): this domain trait does NOT model proration — no supportProration/proration_amount/proration_date/prorationBehavior. A Subscription composing only SaaSBillingBillable silently cannot prorate. To enable proration, compose the CORE financial/Billable trait (which owns the proration semantics). See traits/financial/Billable.trait.yaml.",
    "category": "domain",
    "tags": [
      "billing",
      "pricing",
      "domain"
    ],
    "contexts": [
      "card",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "BillingSummaryBadge",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "amountField": "amount_minor",
          "currencyField": "currency",
          "intervalField": "billing_interval",
          "minorUnits": 100
        }
      },
      {
        "component": "BillingCardMeta",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "amountField": "amount_minor",
          "currencyField": "currency",
          "intervalField": "billing_interval",
          "minorUnits": 100
        }
      }
    ],
    "parameters": [
      {
        "name": "defaultCurrency",
        "type": "string",
        "required": false,
        "description": "ISO 4217 currency used when a plan omits currency.",
        "default": "usd"
      },
      {
        "name": "supportedIntervals",
        "type": "string[]",
        "required": false,
        "description": "Allowed billing intervals that downstream plans may select.",
        "default": [
          "monthly",
          "quarterly",
          "annual"
        ]
      },
      {
        "name": "decimalPrecision",
        "type": "number",
        "required": false,
        "description": "Minor unit precision (ex: cents = 2, yen = 0).",
        "default": 2
      }
    ],
    "schema": {
      "plan_code": {
        "type": "string",
        "required": true,
        "description": "Provider specific identifier for the plan or price."
      },
      "plan_name": {
        "type": "string",
        "required": true,
        "description": "Human readable plan label rendered in list and detail contexts."
      },
      "billing_interval": {
        "type": "string",
        "required": true,
        "description": "Billing cadence name selected from supportedIntervals.",
        "validation": {
          "enumFromParameter": "supportedIntervals"
        }
      },
      "interval_count": {
        "type": "integer",
        "required": false,
        "description": "Multiplier for interval (ex: 12 with monthly => yearly cadence).",
        "default": 1
      },
      "amount_minor": {
        "type": "integer",
        "required": true,
        "description": "Contract value expressed in minor currency units."
      },
      "currency": {
        "type": "string",
        "required": true,
        "description": "ISO 4217 currency for the plan price.",
        "defaultFromParameter": "defaultCurrency"
      },
      "trial_period_days": {
        "type": "integer",
        "required": false,
        "description": "Length of introductory trial period in days."
      },
      "collection_method": {
        "type": "string",
        "required": false,
        "description": "How billing is collected (charge_automatically, send_invoice)."
      },
      "billing_anchor_day": {
        "type": "integer",
        "required": false,
        "description": "Day of month used to anchor renewals when prorating.",
        "validation": {
          "minimum": 1,
          "maximum": 31
        }
      },
      "pricing_model": {
        "type": "string",
        "required": false,
        "description": "Price strategy (flat, per_unit, tiered, package).",
        "default": "flat"
      }
    },
    "semantics": {
      "plan_code": {
        "semantic_type": "billing.plan.code",
        "token_mapping": "tokenMap(billing.plan.code)"
      },
      "plan_name": {
        "semantic_type": "billing.plan.name",
        "token_mapping": "tokenMap(billing.plan.name)"
      },
      "billing_interval": {
        "semantic_type": "billing.plan.interval",
        "token_mapping": "tokenMap(billing.plan.interval)"
      },
      "interval_count": {
        "semantic_type": "billing.plan.interval_count",
        "token_mapping": "tokenMap(billing.plan.interval_count)"
      },
      "amount_minor": {
        "semantic_type": "billing.plan.amount_minor",
        "token_mapping": "tokenMap(billing.plan.amount_minor)",
        "ui_hints": {
          "component": "CurrencyAmount",
          "currencyField": "currency",
          "minorUnits": 100
        }
      },
      "currency": {
        "semantic_type": "billing.plan.currency",
        "token_mapping": "tokenMap(billing.plan.currency)"
      },
      "trial_period_days": {
        "semantic_type": "billing.plan.trial_period_days",
        "token_mapping": "tokenMap(billing.plan.trial_period_days)"
      },
      "collection_method": {
        "semantic_type": "billing.plan.collection_method",
        "token_mapping": "tokenMap(billing.plan.collection_method)"
      },
      "billing_anchor_day": {
        "semantic_type": "billing.plan.billing_anchor_day",
        "token_mapping": "tokenMap(billing.plan.billing_anchor_day)"
      },
      "pricing_model": {
        "semantic_type": "billing.plan.pricing_model",
        "token_mapping": "tokenMap(billing.plan.pricing_model)"
      }
    },
    "tokens": {
      "billing.plan.name": "var(--cmp-text-strong)",
      "billing.plan.amount_minor": "var(--cmp-text-body-strong)",
      "billing.plan.currency": "var(--cmp-text-subtle)",
      "billing.plan.interval": "var(--cmp-text-subtle)",
      "billing.plan.collection_method": "var(--cmp-badge-text-info)"
    },
    "dependencies": [],
    "metadata": {
      "owners": [
        "Billing team",
        "Design team"
      ],
      "maturity": "beta",
      "regionsUsed": [
        "list",
        "card"
      ],
      "references": [
        {
          "R13.5 Canonical Model": "Subscription and Invoice"
        },
        "R4.5 SaaS Enum-to-Token Mapping Schema"
      ]
    },
    "objects": [
      "Plan"
    ],
    "source": "domains/saas-billing/traits/billable.trait.yaml"
  },
  "SaaSBillingMetered": {
    "name": "SaaSBillingMetered",
    "version": "1.0.0",
    "description": "Provides usage metering fields for consumption based billing with normalized units and rollover policy.",
    "category": "domain",
    "tags": [
      "billing",
      "usage",
      "domain"
    ],
    "contexts": [],
    "viewExtensions": [],
    "parameters": [
      {
        "name": "unit",
        "type": "string",
        "required": true,
        "description": "Canonical usage unit label (ex: seats, credits, api_calls).",
        "default": "seats"
      },
      {
        "name": "rolloverStrategy",
        "type": "string",
        "required": false,
        "description": "Determines how unused units are treated at period end.",
        "default": "none",
        "validation": {
          "enum": [
            "none",
            "carry_forward",
            "expire"
          ]
        }
      },
      {
        "name": "sampleWindowDays",
        "type": "integer",
        "required": false,
        "description": "Rolling window size used to calculate usage deltas.",
        "default": 30
      }
    ],
    "schema": {
      "meter_name": {
        "type": "string",
        "required": true,
        "description": "Friendly metered feature name shown in UI (ex: Analytics Seats)."
      },
      "included_quantity": {
        "type": "integer",
        "required": true,
        "description": "Quantity included in base plan before overages."
      },
      "consumed_quantity": {
        "type": "integer",
        "required": true,
        "description": "Actual quantity consumed in the active period."
      },
      "unit_label": {
        "type": "string",
        "required": true,
        "description": "Label for display, defaults to the unit parameter.",
        "defaultFromParameter": "unit"
      },
      "period_start": {
        "type": "date",
        "required": true,
        "description": "Date the usage accumulation window began."
      },
      "period_end": {
        "type": "date",
        "required": true,
        "description": "Date the usage accumulation window ends."
      },
      "rollover_strategy": {
        "type": "string",
        "required": false,
        "description": "Strategy for unused units (inherits rolloverStrategy parameter).",
        "defaultFromParameter": "rolloverStrategy"
      },
      "overage_rate_minor": {
        "type": "integer",
        "required": false,
        "description": "Cost per additional unit expressed in minor currency units."
      },
      "projected_overage_minor": {
        "type": "integer",
        "required": false,
        "description": "Forecasted overage spend derived from consumption trends."
      },
      "samples": {
        "type": "UsageSample[]",
        "required": false,
        "description": "Rolling usage measurements for charts or anomaly detection.",
        "default": []
      }
    },
    "semantics": {
      "meter_name": {
        "semantic_type": "billing.usage.meter_name",
        "token_mapping": "tokenMap(billing.usage.meter_name)"
      },
      "included_quantity": {
        "semantic_type": "billing.usage.included_quantity",
        "token_mapping": "tokenMap(billing.usage.included_quantity)",
        "ui_hints": {
          "format": "quantity"
        }
      },
      "consumed_quantity": {
        "semantic_type": "billing.usage.consumed_quantity",
        "token_mapping": "tokenMap(billing.usage.consumed_quantity)",
        "ui_hints": {
          "format": "quantity"
        }
      },
      "unit_label": {
        "semantic_type": "billing.usage.unit_label",
        "token_mapping": "tokenMap(billing.usage.unit_label)"
      },
      "period_start": {
        "semantic_type": "billing.usage.period_start",
        "token_mapping": "tokenMap(billing.usage.period_start)"
      },
      "period_end": {
        "semantic_type": "billing.usage.period_end",
        "token_mapping": "tokenMap(billing.usage.period_end)"
      },
      "rollover_strategy": {
        "semantic_type": "billing.usage.rollover_strategy",
        "token_mapping": "tokenMap(billing.usage.rollover_strategy)"
      },
      "overage_rate_minor": {
        "semantic_type": "billing.usage.overage_rate_minor",
        "token_mapping": "tokenMap(billing.usage.overage_rate_minor)",
        "ui_hints": {
          "component": "CurrencyAmount",
          "currencyField": "currency",
          "minorUnits": 100
        }
      },
      "projected_overage_minor": {
        "semantic_type": "billing.usage.projected_overage_minor",
        "token_mapping": "tokenMap(billing.usage.projected_overage_minor)",
        "ui_hints": {
          "component": "CurrencyAmount",
          "currencyField": "currency",
          "minorUnits": 100
        }
      },
      "samples": {
        "semantic_type": "billing.usage.samples",
        "token_mapping": "tokenMap(billing.usage.samples)"
      }
    },
    "tokens": {
      "billing.usage.meter_name": "var(--cmp-text-strong)",
      "billing.usage.consumed_quantity": "var(--cmp-text-accent)",
      "billing.usage.projected_overage_minor": "var(--cmp-text-warning)"
    },
    "dependencies": [],
    "metadata": {
      "owners": [
        "Product analytics team"
      ],
      "maturity": "beta",
      "references": [
        {
          "R13.5 Canonical Model": "Subscription and Invoice"
        }
      ]
    },
    "objects": [
      "Plan",
      "Usage"
    ],
    "source": "domains/saas-billing/traits/metered.trait.yaml"
  },
  "SaaSBillingPayable": {
    "name": "SaaSBillingPayable",
    "version": "1.0.0",
    "description": "Captures invoice level billing terms, status, and outstanding balance metadata for SaaS finance teams.",
    "category": "domain",
    "tags": [
      "billing",
      "invoice",
      "domain"
    ],
    "contexts": [
      "card",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "BillingSummaryBadge",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "amountField": "total_minor",
          "currencyField": "currency",
          "minorUnits": 100,
          "showInterval": false
        }
      },
      {
        "component": "BillingSummaryBadge",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "amountField": "total_minor",
          "currencyField": "currency",
          "minorUnits": 100,
          "showInterval": false
        }
      }
    ],
    "parameters": [
      {
        "name": "statusEnum",
        "type": "string[]",
        "required": true,
        "description": "Canonical invoice status values allowed by the domain.",
        "default": [
          "draft",
          "posted",
          "open",
          "processing",
          "past_due",
          "paid",
          "refunded",
          "uncollectible",
          "void"
        ]
      },
      {
        "name": "paymentTerms",
        "type": "string[]",
        "required": false,
        "description": "Supported payment term descriptors (ex: net_15, due_upon_receipt).",
        "default": [
          "due_upon_receipt",
          "net_15",
          "net_30",
          "net_45"
        ]
      }
    ],
    "schema": {
      "invoice_number": {
        "type": "string",
        "required": true,
        "description": "Human readable invoice identifier presented to customers."
      },
      "status": {
        "type": "string",
        "required": true,
        "description": "Canonical invoice status after provider mapping.",
        "validation": {
          "enumFromParameter": "statusEnum"
        }
      },
      "provider_status": {
        "type": "string",
        "required": false,
        "description": "Original provider reported status or badge."
      },
      "issued_at": {
        "type": "datetime",
        "required": true,
        "description": "Timestamp when the invoice was finalized or posted."
      },
      "due_at": {
        "type": "datetime",
        "required": false,
        "description": "Payment due timestamp derived from payment terms."
      },
      "paid_at": {
        "type": "datetime",
        "required": false,
        "description": "Timestamp when full payment cleared."
      },
      "total_minor": {
        "type": "integer",
        "required": true,
        "description": "Total amount due expressed in minor currency units."
      },
      "balance_minor": {
        "type": "integer",
        "required": false,
        "description": "Remaining amount outstanding in minor units.",
        "default": 0
      },
      "currency": {
        "type": "string",
        "required": true,
        "description": "ISO 4217 currency for the invoice."
      },
      "payment_terms": {
        "type": "string",
        "required": false,
        "description": "Payment term label describing when payment is expected.",
        "validation": {
          "enumFromParameter": "paymentTerms"
        }
      },
      "collection_state": {
        "type": "string",
        "required": false,
        "description": "Dunning phase or retry program detail presented to success teams."
      },
      "last_reminder_at": {
        "type": "datetime",
        "required": false,
        "description": "Timestamp of most recent payment reminder issued to customer."
      },
      "aging_bucket_days": {
        "type": "integer",
        "required": false,
        "description": "Number of days outstanding grouped for aging reports."
      },
      "attempt_count": {
        "type": "integer",
        "required": false,
        "description": "Number of automatic payment attempts made on this invoice (Stripe smart-retries attempt_count). Increments on each retry in the dunning window. Source: docs.stripe.com/billing/revenue-recovery/smart-retries.",
        "default": 0,
        "validation": {
          "minimum": 0
        }
      },
      "next_payment_attempt": {
        "type": "datetime",
        "required": false,
        "description": "When the next automatic payment retry is scheduled (Stripe smart-retries next_payment_attempt). Defines the open end of the retry window — modeled on the Refundable.refundable_until datetime-window precedent. Absent/null when no further attempts are scheduled (retries exhausted → invoice goes uncollectible, mirroring the subscription `unpaid` state). Source: docs.stripe.com/billing/revenue-recovery/smart-retries."
      },
      "memo": {
        "type": "string",
        "required": false,
        "description": "Internal finance note or customer visible memo."
      }
    },
    "semantics": {
      "invoice_number": {
        "semantic_type": "billing.invoice.number",
        "token_mapping": "tokenMap(billing.invoice.number)"
      },
      "status": {
        "semantic_type": "billing.invoice.status",
        "token_mapping": "tokenMap(billing.invoice.status.*)"
      },
      "provider_status": {
        "semantic_type": "billing.invoice.provider_status",
        "token_mapping": "tokenMap(billing.invoice.provider_status)"
      },
      "issued_at": {
        "semantic_type": "billing.invoice.issued_at",
        "token_mapping": "tokenMap(billing.invoice.issued_at)"
      },
      "due_at": {
        "semantic_type": "billing.invoice.due_at",
        "token_mapping": "tokenMap(billing.invoice.due_at)"
      },
      "paid_at": {
        "semantic_type": "billing.invoice.paid_at",
        "token_mapping": "tokenMap(billing.invoice.paid_at)"
      },
      "total_minor": {
        "semantic_type": "billing.invoice.total_minor",
        "token_mapping": "tokenMap(billing.invoice.total_minor)",
        "ui_hints": {
          "component": "CurrencyAmount",
          "currencyField": "currency",
          "minorUnits": 100
        }
      },
      "balance_minor": {
        "semantic_type": "billing.invoice.balance_minor",
        "token_mapping": "tokenMap(billing.invoice.balance_minor)",
        "ui_hints": {
          "component": "CurrencyAmount",
          "currencyField": "currency",
          "minorUnits": 100
        }
      },
      "currency": {
        "semantic_type": "billing.invoice.currency",
        "token_mapping": "tokenMap(billing.invoice.currency)"
      },
      "payment_terms": {
        "semantic_type": "billing.invoice.payment_terms",
        "token_mapping": "tokenMap(billing.invoice.payment_terms)"
      },
      "collection_state": {
        "semantic_type": "billing.invoice.collection_state",
        "token_mapping": "tokenMap(billing.invoice.collection_state)"
      },
      "last_reminder_at": {
        "semantic_type": "billing.invoice.last_reminder_at",
        "token_mapping": "tokenMap(billing.invoice.last_reminder_at)"
      },
      "aging_bucket_days": {
        "semantic_type": "billing.invoice.aging_bucket_days",
        "token_mapping": "tokenMap(billing.invoice.aging_bucket_days)"
      },
      "attempt_count": {
        "semantic_type": "billing.invoice.attempt_count",
        "token_mapping": "tokenMap(billing.invoice.attempt_count)"
      },
      "next_payment_attempt": {
        "semantic_type": "billing.invoice.next_payment_attempt",
        "token_mapping": "tokenMap(billing.invoice.next_payment_attempt)"
      },
      "memo": {
        "semantic_type": "billing.invoice.memo",
        "token_mapping": "tokenMap(billing.invoice.memo)"
      }
    },
    "tokens": {
      "billing.invoice.number": "var(--cmp-text-strong)",
      "billing.invoice.total_minor": "var(--cmp-text-body-strong)",
      "billing.invoice.balance_minor": "var(--cmp-text-warning)",
      "billing.invoice.status.past_due": "var(--cmp-status-critical-text)",
      "billing.invoice.status.paid": "var(--cmp-status-success-text)"
    },
    "dependencies": [],
    "metadata": {
      "owners": [
        "Revenue ops team"
      ],
      "maturity": "beta",
      "regionsUsed": [
        "list",
        "card"
      ],
      "notes": [
        "Canonical status options sourced from r4.5 mapping research.",
        "Dunning/access reconciliation (s126-m05, scoped to the access-revocation need): the 9-value statusEnum is a SUPERSET of the canonical 5-state invoice model (draft, posted, paid, past_due, void — see docs/billing/lifecycle-states.md). Dunning-relevant mapping: `open`/`processing` = pre-dunning (awaiting/settling payment); `past_due` = overdue, retries ongoing → subscription past_due (GRACE, keep access); `uncollectible` = retries exhausted → mirrors subscription `unpaid` (REVOKE access). The retry window is carried by attempt_count + next_payment_attempt. The subscription-status → access decision is encoded in src/domain/billing/states.ts hasServiceAccess()."
      ]
    },
    "objects": [
      "Invoice"
    ],
    "source": "domains/saas-billing/traits/payable.trait.yaml"
  },
  "SaaSBillingRefundable": {
    "name": "SaaSBillingRefundable",
    "version": "1.0.0",
    "description": "Describes refund eligibility, policy windows, and credit memo tracking for SaaS billing flows.",
    "category": "domain",
    "tags": [
      "billing",
      "refund",
      "domain"
    ],
    "contexts": [],
    "viewExtensions": [],
    "parameters": [
      {
        "name": "defaultWindowDays",
        "type": "integer",
        "required": false,
        "description": "Default number of days after payment where refunds are allowed.",
        "default": 30
      },
      {
        "name": "creditMemoTypes",
        "type": "string[]",
        "required": false,
        "description": "Supported credit memo categories used by finance teams.",
        "default": [
          "service_failure",
          "retention_incentive",
          "goodwill"
        ]
      }
    ],
    "schema": {
      "refundable_until": {
        "type": "datetime",
        "required": false,
        "description": "Date when refund eligibility window ends for this record."
      },
      "refund_policy_url": {
        "type": "string",
        "required": false,
        "description": "Link to customer facing refund or cancellation policy."
      },
      "total_refunded_minor": {
        "type": "integer",
        "required": false,
        "description": "Cumulative amount refunded in minor currency units.",
        "default": 0
      },
      "credit_memo_balance_minor": {
        "type": "integer",
        "required": false,
        "description": "Remaining credit memo balance that can be applied to invoices.",
        "default": 0
      },
      "credit_memo_type": {
        "type": "string",
        "required": false,
        "description": "Category of credit memo tied to business justification.",
        "validation": {
          "enumFromParameter": "creditMemoTypes"
        }
      },
      "last_refund_at": {
        "type": "datetime",
        "required": false,
        "description": "Timestamp when the most recent refund was issued."
      },
      "requires_manager_approval": {
        "type": "boolean",
        "required": false,
        "description": "Indicates if finance manager approval is required before issuing refund.",
        "default": false
      },
      "notes": {
        "type": "string",
        "required": false,
        "description": "Internal commentary about refund actions or policy exceptions."
      }
    },
    "semantics": {
      "refundable_until": {
        "semantic_type": "billing.refund.window_end",
        "token_mapping": "tokenMap(billing.refund.window_end)"
      },
      "refund_policy_url": {
        "semantic_type": "billing.refund.policy_link",
        "token_mapping": "tokenMap(billing.refund.policy_link)"
      },
      "total_refunded_minor": {
        "semantic_type": "billing.refund.total_minor",
        "token_mapping": "tokenMap(billing.refund.total_minor)",
        "ui_hints": {
          "component": "CurrencyAmount",
          "currencyField": "currency",
          "minorUnits": 100
        }
      },
      "credit_memo_balance_minor": {
        "semantic_type": "billing.refund.credit_memo_balance_minor",
        "token_mapping": "tokenMap(billing.refund.credit_memo_balance_minor)",
        "ui_hints": {
          "component": "CurrencyAmount",
          "currencyField": "currency",
          "minorUnits": 100
        }
      },
      "credit_memo_type": {
        "semantic_type": "billing.refund.credit_memo_type",
        "token_mapping": "tokenMap(billing.refund.credit_memo_type)"
      },
      "last_refund_at": {
        "semantic_type": "billing.refund.last_refund_at",
        "token_mapping": "tokenMap(billing.refund.last_refund_at)"
      },
      "requires_manager_approval": {
        "semantic_type": "billing.refund.requires_manager_approval",
        "token_mapping": "tokenMap(billing.refund.requires_manager_approval)"
      },
      "notes": {
        "semantic_type": "billing.refund.notes",
        "token_mapping": "tokenMap(billing.refund.notes)"
      }
    },
    "tokens": {
      "billing.refund.total_minor": "var(--cmp-text-accent)",
      "billing.refund.credit_memo_balance_minor": "var(--cmp-text-info)",
      "billing.refund.requires_manager_approval": "var(--cmp-badge-text-warning)"
    },
    "dependencies": [],
    "metadata": {
      "owners": [
        "Finance team"
      ],
      "maturity": "experimental",
      "notes": [
        "Aligns with refund governance requirements captured in billing domain research."
      ]
    },
    "objects": [
      "Invoice"
    ],
    "source": "domains/saas-billing/traits/refundable.trait.yaml"
  },
  "ScaleLinear": {
    "name": "ScaleLinear",
    "version": "0.2.1",
    "description": "Shared linear/continuous scale definition used by positional, color, and\nsize encodings. Provides normalized domain/range metadata plus zero baseline\nenforcement per RDV.3 findings.",
    "category": "viz.scale",
    "tags": [
      "viz",
      "scale",
      "linear"
    ],
    "contexts": [
      "detail",
      "form"
    ],
    "viewExtensions": [
      {
        "component": "VizScaleSummary",
        "context": "detail",
        "position": "sidebar",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "type": "linear",
          "domainMinField": "viz_scale_linear_domain_min",
          "domainMaxField": "viz_scale_linear_domain_max",
          "modeField": "viz_scale_linear_mode",
          "zeroField": "viz_scale_linear_zero_baseline"
        }
      },
      {
        "component": "VizScaleControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "type": "linear",
          "domainMinField": "viz_scale_linear_domain_min",
          "domainMaxField": "viz_scale_linear_domain_max",
          "rangeMinField": "viz_scale_linear_range_min",
          "rangeMaxField": "viz_scale_linear_range_max",
          "zeroField": "viz_scale_linear_zero_baseline",
          "modeField": "viz_scale_linear_mode"
        }
      }
    ],
    "parameters": [
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment for the governed authoring recipes. Data rows remain a consumer operand."
      },
      {
        "name": "domainMin",
        "type": "number",
        "required": true,
        "description": "Default lower domain bound applied when unspecified.",
        "default": 0
      },
      {
        "name": "domainMax",
        "type": "number",
        "required": true,
        "description": "Default upper domain bound applied when unspecified.",
        "default": 1
      },
      {
        "name": "rangeMin",
        "type": "number",
        "required": true,
        "description": "Default lower range bound (normalized 0-1).",
        "default": 0
      },
      {
        "name": "rangeMax",
        "type": "number",
        "required": true,
        "description": "Default upper range bound (normalized 0-1).",
        "default": 1
      },
      {
        "name": "clamp",
        "type": "boolean",
        "required": false,
        "description": "Whether values outside the domain should clamp to edges.",
        "default": true
      },
      {
        "name": "zeroBaseline",
        "type": "boolean",
        "required": false,
        "description": "Forces zero to be included in the domain.",
        "default": true
      },
      {
        "name": "mode",
        "type": "string",
        "required": false,
        "description": "Whether this scale behaves as continuous or band for categories.",
        "default": "continuous",
        "validation": {
          "enum": [
            "continuous",
            "band"
          ]
        }
      }
    ],
    "schema": {
      "viz_scale_linear_domain_min": {
        "type": "number",
        "required": true,
        "description": "Lower domain bound for continuous encodings.",
        "defaultFromParameter": "domainMin"
      },
      "viz_scale_linear_domain_max": {
        "type": "number",
        "required": true,
        "description": "Upper domain bound for continuous encodings.",
        "defaultFromParameter": "domainMax"
      },
      "viz_scale_linear_range_min": {
        "type": "number",
        "required": true,
        "description": "Lower range bound (normalized 0-1).",
        "defaultFromParameter": "rangeMin"
      },
      "viz_scale_linear_range_max": {
        "type": "number",
        "required": true,
        "description": "Upper range bound (normalized 0-1).",
        "defaultFromParameter": "rangeMax"
      },
      "viz_scale_linear_clamp": {
        "type": "boolean",
        "required": false,
        "description": "Indicates whether values outside the domain clamp to bounds.",
        "defaultFromParameter": "clamp"
      },
      "viz_scale_linear_zero_baseline": {
        "type": "boolean",
        "required": false,
        "description": "Forces zero within the domain for accessibility compliance.",
        "defaultFromParameter": "zeroBaseline"
      },
      "viz_scale_linear_mode": {
        "type": "string",
        "required": false,
        "description": "Distinguishes continuous vs band heuristics.",
        "defaultFromParameter": "mode",
        "validation": {
          "enum": [
            "continuous",
            "band"
          ]
        }
      },
      "viz_scale_linear_description": {
        "type": "string",
        "required": false,
        "description": "Narrative summary for fallbacks.",
        "default": "Linear scale with governed domain/range."
      }
    },
    "semantics": {
      "viz_scale_linear_domain_min": {
        "semantic_type": "viz.scale.domain",
        "token_mapping": "tokenMap(viz.scale.domain)",
        "ui_hints": {
          "component": "NumericPreview"
        }
      },
      "viz_scale_linear_domain_max": {
        "semantic_type": "viz.scale.domain",
        "token_mapping": "tokenMap(viz.scale.domain)",
        "ui_hints": {
          "component": "NumericPreview"
        }
      },
      "viz_scale_linear_mode": {
        "semantic_type": "viz.scale.mode",
        "token_mapping": "tokenMap(viz.scale.mode)",
        "ui_hints": {
          "component": "TextBadge"
        }
      },
      "viz_scale_linear_zero_baseline": {
        "semantic_type": "viz.scale.zero",
        "token_mapping": "tokenMap(viz.scale.zero)",
        "ui_hints": {
          "component": "BooleanBadge"
        }
      }
    },
    "tokens": {
      "viz.scale.linear.grid": "var(--cmp-viz-grid-line)",
      "viz.scale.linear.axis": "var(--cmp-viz-axis-line)",
      "viz.scale.linear.zero": "var(--cmp-viz-zero-line)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-15",
      "updated": "2026-02-28",
      "owners": [
        "Viz team",
        "Platform team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "Scale controls are keyboard-operable in VizScaleControls form component.",
        "screenreader": "Scale summary announces domain range and zero baseline status."
      },
      "regionsUsed": [
        "detail",
        "form"
      ],
      "allows": [
        "EncodingPositionX",
        "EncodingPositionY",
        "EncodingSize",
        "EncodingColor"
      ],
      "references": [
        "RDS.7 Trait-Driven Visualization System Specification (v0.1)"
      ]
    },
    "objects": [],
    "source": "traits/viz/scale-linear.trait.yaml"
  },
  "ScaleTemporal": {
    "name": "ScaleTemporal",
    "version": "0.3.1",
    "description": "Temporal scale metadata with UTC rendering. Version 0.3.0 removes the unused\ntimezone parameter (breaking); axes and tooltips continue to render in UTC.",
    "category": "viz.scale",
    "tags": [
      "viz",
      "scale",
      "temporal"
    ],
    "contexts": [
      "detail",
      "form"
    ],
    "viewExtensions": [
      {
        "component": "VizScaleSummary",
        "context": "detail",
        "position": "sidebar",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "type": "temporal",
          "domainMinField": "viz_scale_temporal_domain_start",
          "domainMaxField": "viz_scale_temporal_domain_end",
          "niceField": "viz_scale_temporal_nice"
        }
      },
      {
        "component": "VizScaleControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent",
          "type": "temporal",
          "domainMinField": "viz_scale_temporal_domain_start",
          "domainMaxField": "viz_scale_temporal_domain_end",
          "rangeMinField": "viz_scale_temporal_range_min",
          "rangeMaxField": "viz_scale_temporal_range_max",
          "niceField": "viz_scale_temporal_nice",
          "formatField": "viz_scale_temporal_output_format"
        }
      }
    ],
    "parameters": [
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment for the governed authoring recipes. Data rows remain a consumer operand."
      },
      {
        "name": "domainStart",
        "type": "string",
        "required": true,
        "description": "ISO-8601 timestamp representing the lower bound.",
        "default": "2024-01-01T00:00:00Z"
      },
      {
        "name": "domainEnd",
        "type": "string",
        "required": true,
        "description": "ISO-8601 timestamp representing the upper bound.",
        "default": "2024-12-31T23:59:59Z"
      },
      {
        "name": "rangeMin",
        "type": "number",
        "required": true,
        "description": "Normalized lower range bound (0-1).",
        "default": 0
      },
      {
        "name": "rangeMax",
        "type": "number",
        "required": true,
        "description": "Normalized upper range bound (0-1).",
        "default": 1
      },
      {
        "name": "nice",
        "type": "string",
        "required": false,
        "description": "Interval used when rounding ticks.",
        "default": "month",
        "validation": {
          "enum": [
            "day",
            "week",
            "month",
            "quarter",
            "year"
          ]
        }
      },
      {
        "name": "outputFormat",
        "type": "string",
        "required": false,
        "description": "Default date format string for axes + fallbacks.",
        "default": "YYYY-MM-DD"
      }
    ],
    "schema": {
      "viz_scale_temporal_domain_start": {
        "type": "string",
        "required": true,
        "description": "ISO timestamp representing lower bound.",
        "defaultFromParameter": "domainStart"
      },
      "viz_scale_temporal_domain_end": {
        "type": "string",
        "required": true,
        "description": "ISO timestamp representing upper bound.",
        "defaultFromParameter": "domainEnd"
      },
      "viz_scale_temporal_range_min": {
        "type": "number",
        "required": true,
        "description": "Normalized lower range bound.",
        "defaultFromParameter": "rangeMin"
      },
      "viz_scale_temporal_range_max": {
        "type": "number",
        "required": true,
        "description": "Normalized upper range bound.",
        "defaultFromParameter": "rangeMax"
      },
      "viz_scale_temporal_nice": {
        "type": "string",
        "required": false,
        "description": "Interval used when rounding ticks.",
        "defaultFromParameter": "nice",
        "validation": {
          "enum": [
            "day",
            "week",
            "month",
            "quarter",
            "year"
          ]
        }
      },
      "viz_scale_temporal_output_format": {
        "type": "string",
        "required": false,
        "description": "Default format string for textual output.",
        "defaultFromParameter": "outputFormat"
      },
      "viz_scale_temporal_description": {
        "type": "string",
        "required": false,
        "description": "Narrative summary for fallback contexts.",
        "default": "Temporal scale rendered in UTC."
      }
    },
    "semantics": {
      "viz_scale_temporal_domain_start": {
        "semantic_type": "viz.scale.domain",
        "token_mapping": "tokenMap(viz.scale.domain)",
        "ui_hints": {
          "component": "TimestampPreview"
        }
      },
      "viz_scale_temporal_domain_end": {
        "semantic_type": "viz.scale.domain",
        "token_mapping": "tokenMap(viz.scale.domain)",
        "ui_hints": {
          "component": "TimestampPreview"
        }
      },
      "viz_scale_temporal_nice": {
        "semantic_type": "viz.scale.nice",
        "token_mapping": "tokenMap(viz.scale.nice)",
        "ui_hints": {
          "component": "TextBadge"
        }
      }
    },
    "tokens": {
      "viz.scale.temporal.grid": "var(--cmp-viz-grid-line)",
      "viz.scale.temporal.axis": "var(--cmp-viz-axis-line)",
      "viz.scale.temporal.tick": "var(--cmp-viz-axis-tick)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-11-15",
      "updated": "2026-09-14",
      "owners": [
        "Viz team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "Temporal scale controls are keyboard-operable in VizScaleControls form.",
        "screenreader": "Temporal axes and tooltips use UTC."
      },
      "regionsUsed": [
        "detail",
        "form"
      ],
      "allows": [
        "EncodingPositionX",
        "EncodingPositionY"
      ],
      "references": [
        "RDS.7 Trait-Driven Visualization System Specification (v0.1)"
      ]
    },
    "objects": [],
    "source": "traits/viz/scale-temporal.trait.yaml"
  },
  "ScatterPlot": {
    "name": "ScatterPlot",
    "version": "0.1.1",
    "description": "Scatter authoring over the existing MarkPoint renderer",
    "category": "viz.pattern",
    "tags": [
      "viz",
      "authoring"
    ],
    "contexts": [
      "detail",
      "form"
    ],
    "viewExtensions": [
      {
        "component": "VizScatterControls",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "intentParameter": "renderIntent"
        }
      },
      {
        "component": "VizScatterPreview",
        "context": "detail",
        "position": "top",
        "priority": null,
        "props": {
          "svgParameter": "previewSvg"
        }
      }
    ],
    "parameters": [
      {
        "name": "renderIntent",
        "type": "string",
        "required": false,
        "default": "{}",
        "description": "JSON-encoded Cartesian viz_render input fragment; data rows are supplied by the consumer."
      },
      {
        "name": "previewSvg",
        "type": "string",
        "required": false,
        "description": "Static SVG returned by viz_render for the authored sample."
      }
    ],
    "schema": {},
    "semantics": {},
    "tokens": {},
    "dependencies": [],
    "metadata": {
      "regionsUsed": [
        "form",
        "detail"
      ]
    },
    "objects": [],
    "source": "traits/viz/scatter-plot.trait.yaml"
  },
  "Searchable": {
    "name": "Searchable",
    "version": "1.0.0",
    "description": "Adds full-text search capability to list and collection views. Searchable injects a search\ninput into the header region, wires query state to the data layer, and provides semantic\ntoken mappings for consistent search UI styling across brands.\n\nThe trait supports placeholder text customization, debounce control for performance,\nand clear-on-escape behavior. Search state is managed via the searchQuery prop, which\nthe consuming layout binds to a data filter or API parameter.",
    "category": "behavioral",
    "tags": [
      "search",
      "filtering",
      "discovery",
      "list-behavior"
    ],
    "contexts": [
      "detail",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "SearchInput",
        "context": "list",
        "position": "header",
        "priority": 10,
        "props": {
          "field": "searchQuery",
          "placeholderParameter": "placeholder",
          "debounceParameter": "debounceMs",
          "minQueryLengthParameter": "minQueryLength",
          "clearableParameter": "clearable"
        }
      },
      {
        "component": "SearchInput",
        "context": "detail",
        "position": "header",
        "priority": 10,
        "props": {
          "field": "searchQuery",
          "placeholderParameter": "placeholder",
          "clearableParameter": "clearable"
        }
      }
    ],
    "parameters": [
      {
        "name": "placeholder",
        "type": "string",
        "required": false,
        "description": "Placeholder text shown in the search input when empty.",
        "default": "Search..."
      },
      {
        "name": "debounceMs",
        "type": "number",
        "required": false,
        "description": "Debounce delay in milliseconds before the search query is emitted.\nPrevents excessive re-renders or API calls while the user is typing.\n",
        "default": 300,
        "validation": {
          "minimum": 0,
          "maximum": 2000
        }
      },
      {
        "name": "minQueryLength",
        "type": "number",
        "required": false,
        "description": "Minimum number of characters before the search triggers.\nPrevents overly broad queries on large datasets.\n",
        "default": 1,
        "validation": {
          "minimum": 0,
          "maximum": 10
        }
      },
      {
        "name": "clearable",
        "type": "boolean",
        "required": false,
        "description": "Whether the search input shows a clear button when non-empty.",
        "default": true
      }
    ],
    "schema": {
      "searchQuery": {
        "type": "string",
        "required": false,
        "description": "The current search query string entered by the user.",
        "default": "",
        "validation": {
          "maxLength": 256
        }
      },
      "searchActive": {
        "type": "boolean",
        "required": false,
        "description": "Whether the search input is currently focused or has a non-empty query.",
        "default": false
      }
    },
    "semantics": {
      "searchQuery": {
        "semantic_type": "input.search.query",
        "token_mapping": "tokenMap(search.input.*)",
        "ui_hints": {
          "component": "SearchInput",
          "placeholderParameter": "placeholder",
          "debounceParameter": "debounceMs"
        }
      },
      "searchActive": {
        "semantic_type": "state.search.active",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "SearchInput",
          "description": "Drives visual active/inactive state of the search region."
        }
      }
    },
    "tokens": {
      "search.input.bg": "var(--sys-surface-default)",
      "search.input.text": "var(--sys-text-primary)",
      "search.input.placeholder": "var(--sys-text-subtle)",
      "search.input.border": "var(--sys-border-default)",
      "search.input.focus.border": "var(--sys-border-focus)",
      "search.input.focus.ring": "var(--sys-focus-ring)",
      "search.input.icon": "var(--sys-icon-subtle)",
      "search.input.clear.hover": "var(--sys-surface-hover)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2026-03-05",
      "updated": "2026-03-05",
      "owners": [
        "Design team"
      ],
      "maturity": "stable",
      "accessibility": {
        "keyboard": "SearchInput supports full keyboard navigation:\n- Type to enter search query\n- Escape to clear the search input\n- Tab to move focus out of the search input\n",
        "screenreader": "Search input is labelled with role=\"search\" and an accessible name.\nCurrent query state is announced via aria-live region on debounce completion.\nClear button is announced as \"Clear search\".\n"
      },
      "regionsUsed": [
        "list",
        "detail"
      ],
      "examples": [
        "Product catalog search",
        "User directory search",
        "Knowledge base search"
      ],
      "references": [
        "Trait Engine Spec v0.1 section 2"
      ]
    },
    "objects": [
      "Product"
    ],
    "source": "traits/behavioral/Searchable.trait.yaml"
  },
  "Sortable": {
    "name": "Sortable",
    "version": "1.0.0",
    "description": "Adds column sorting controls to list and table views. Sortable injects sort indicators\ninto the header region near column headers, wires sort state to the data layer, and\nprovides semantic token mappings for consistent sort UI styling across brands.\n\nThe trait supports single-column sorting with ascending/descending/none cycle.\nSort state is managed via sortField and sortDirection props, which the consuming layout\nbinds to data ordering parameters or API sort queries.",
    "category": "behavioral",
    "tags": [
      "sorting",
      "list-behavior",
      "table",
      "ordering"
    ],
    "contexts": [
      "list"
    ],
    "viewExtensions": [
      {
        "component": "SortIndicator",
        "context": "list",
        "position": "header",
        "priority": 8,
        "props": {
          "sortFieldProp": "sortField",
          "sortDirectionProp": "sortDirection",
          "sortableFieldsParameter": "sortableFields",
          "triStateSortParameter": "triStateSort",
          "defaultSortFieldParameter": "defaultSortField",
          "defaultSortDirectionParameter": "defaultSortDirection"
        }
      }
    ],
    "parameters": [
      {
        "name": "defaultSortField",
        "type": "string",
        "required": false,
        "description": "The field name to sort by on initial load. Empty means no default sort.",
        "default": ""
      },
      {
        "name": "defaultSortDirection",
        "type": "string",
        "required": false,
        "description": "Default sort direction on initial load.",
        "default": "asc",
        "validation": {
          "enum": [
            "asc",
            "desc"
          ]
        }
      },
      {
        "name": "sortableFields",
        "type": "string[]",
        "required": false,
        "description": "List of field names that support sorting. When empty, all fields in the schema are\nconsidered sortable. When specified, only these fields show sort controls in the header.\n",
        "default": [],
        "validation": {
          "uniqueItems": true
        }
      },
      {
        "name": "triStateSort",
        "type": "boolean",
        "required": false,
        "description": "When true, sort cycles through ascending → descending → none (unsorted).\nWhen false, sort toggles between ascending and descending only.\n",
        "default": true
      }
    ],
    "schema": {
      "sortField": {
        "type": "string",
        "required": false,
        "description": "The currently active sort field name. Empty string means no active sort.",
        "default": ""
      },
      "sortDirection": {
        "type": "string",
        "required": false,
        "description": "Current sort direction.",
        "default": "asc",
        "validation": {
          "enum": [
            "asc",
            "desc"
          ]
        }
      },
      "sortActive": {
        "type": "boolean",
        "required": false,
        "description": "Whether sorting is currently applied (sortField is non-empty).",
        "default": false
      }
    },
    "semantics": {
      "sortField": {
        "semantic_type": "state.sort.field",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "SortIndicator",
          "defaultParameter": "defaultSortField"
        }
      },
      "sortDirection": {
        "semantic_type": "state.sort.direction",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "SortIndicator",
          "defaultParameter": "defaultSortDirection"
        }
      },
      "sortActive": {
        "semantic_type": "state.sort.active",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "SortIndicator",
          "description": "Drives visual highlight of the sorted column header."
        }
      }
    },
    "tokens": {
      "sort.indicator.idle": "var(--sys-icon-subtle)",
      "sort.indicator.active": "var(--sys-icon-primary)",
      "sort.indicator.hover": "var(--sys-icon-hover)",
      "sort.header.hover.bg": "var(--sys-surface-hover)",
      "sort.header.active.bg": "var(--sys-surface-accent-subtle)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2026-03-05",
      "updated": "2026-03-05",
      "owners": [
        "Design team"
      ],
      "maturity": "stable",
      "accessibility": {
        "keyboard": "Sort controls are activated via column header buttons:\n- Enter/Space to cycle sort direction on the focused column\n- Tab to move between sortable column headers\n- Sort state change is announced immediately\n",
        "screenreader": "Sortable column headers use button role with aria-sort attribute\n(ascending, descending, or none). On activation, the new sort state\nis announced via aria-live region (e.g., \"Sorted by Name, ascending\").\nNon-sortable columns do not have interactive sort controls.\n"
      },
      "regionsUsed": [
        "list"
      ],
      "examples": [
        "Product catalog column sorting",
        "User directory sorting",
        "Invoice list sorting"
      ],
      "references": [
        "Trait Engine Spec v0.1 section 2"
      ]
    },
    "objects": [],
    "source": "traits/behavioral/Sortable.trait.yaml"
  },
  "Stateful": {
    "name": "Stateful",
    "version": "2.5.1",
    "description": "Normalizes lifecycle state transitions, exposes canonical status semantics, and provides\noptional transition governance for production workflows. Many objects compose Stateful\n(User, Subscription and Product among them), and it serves as the data source for the\nColorized visual trait.\n\nAt its simplest, Stateful defines an ordered list of valid states and tracks the current\nstatus. With transitionRules, a product also declares which moves between states are allowed,\nfor auditable workflows where arbitrary state jumps are not permitted.\nYour product enforces that order on its own records: it checks each change against it and writes\nallowed_transitions. OODS Foundry keeps the order as data, refuses an order that names a state the\nlifecycle lacks and holds its own shipped samples to it. A generated app keeps the order in its own\nstore: a generated StatusSelector offers the record's state and the moves the order allows from it,\nand the store refuses any other move and any move out of a final state. In generated React and Vue\nscreens, Cancel is offered, and the store accepts it, only from a state the order lets move to where\ncancelling goes. With actions, a lifecycle also names the moves a person makes, such as a grant's\nRevoke, Pause and Resume: each is offered only from the states it moves from, is written as one\nchange to the app's own records, and stops nothing. Every recorded change, with an order or without one,\ncan name who made it and why.",
    "category": "lifecycle",
    "tags": [
      "lifecycle",
      "status",
      "workflow",
      "state",
      "governance",
      "audit"
    ],
    "contexts": [
      "card",
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "StatusBadge",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "field": "status",
          "tone": "lifecycle"
        }
      },
      {
        "component": "StatusTimeline",
        "context": "detail",
        "position": "top",
        "priority": 40,
        "props": {
          "field": "status",
          "historyField": "state_history",
          "statesParameter": "states",
          "showActorId": true,
          "showReason": true
        }
      },
      {
        "component": "StatusSelector",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "field": "status",
          "optionsParameter": "states",
          "initialParameter": "initialState",
          "allowedTransitionsField": "allowed_transitions",
          "requireReasonParameter": "requireTransitionReason"
        }
      },
      {
        "component": "StatusBadge",
        "context": "card",
        "position": "before",
        "priority": null,
        "props": {
          "field": "status",
          "variant": "subtle"
        }
      }
    ],
    "parameters": [
      {
        "name": "states",
        "type": "string[]",
        "required": true,
        "description": "Ordered list of valid lifecycle states exposed to consumers. The order is semantic —\nit represents the typical forward progression (e.g., draft → active → archived).\nAll status values must be one of these states.\n",
        "default": [
          "draft",
          "active",
          "paused",
          "archived"
        ]
      },
      {
        "name": "initialState",
        "type": "string",
        "required": true,
        "description": "State assigned when an entity is created. Must be a member of the states parameter.\nTypically the first entry in the states list (e.g., \"draft\").\n",
        "default": "draft",
        "validation": {
          "enumFromParameter": "states"
        }
      },
      {
        "name": "transitionRules",
        "type": "Record<string, string[]>",
        "required": false,
        "description": "Allowed state transition map. Keys are source states; values are arrays of permitted\ntarget states, and an empty array marks a final state. Every key and target must be one of\nthe states: an order that names a state the lifecycle lacks is refused. Your product enforces\nthe order and rejects any other move. OODS Foundry keeps it as data, and a generated app keeps\nit in its own store: its status select offers the current state and the moves allowed from it,\nits store refuses any other move and any move out of a final state, and Cancel and the declared\nactions are offered only where the order allows. When omitted, a move between any two states is\nallowed (open model).\n\nExample for a subscription lifecycle:\n  draft: [active, archived]\n  active: [paused, archived]\n  paused: [active, archived]\n  archived: []\n",
        "default": null
      },
      {
        "name": "actions",
        "type": "object[]",
        "required": false,
        "description": "Named moves a person makes on a record, each to one state of the declared order: its id, the state it\nmoves to (to), the states it is offered from (from; by default every state whose declared targets include to),\nthe verb a person reads (verb), and the event Timestampable records for it (event). It may also name the field its\noptional note is written to (reasonField), the seat whose _id, _name and _kind fields name who acted when the app\nis told (bySeat), whether it asks once first (confirm), and the records of the same object that make the same move\nwith it (alsoEnds: { via }). Each action needs transitionRules. A generated screen offers an action only from the\nstates it moves from, and a generated app writes it as one change to its own records when a person asks; it stops\nnothing. A record whose object declares an action ending it (to a final state) is ended, never deleted, so its\ndetail offers no Delete.\nExample for a grant:\n  - { id: revoke, to: revoked, verb: Revoke, event: ended, reasonField: ended_reason, bySeat: ended_by, confirm: true, alsoEnds: { via: within_id } }\n  - { id: pause, to: paused, verb: Pause, event: paused }\n  - { id: resume, from: [paused], to: active, verb: Resume, event: resumed }\n",
        "default": null
      },
      {
        "name": "requireTransitionReason",
        "type": "boolean",
        "required": false,
        "description": "When true, your product requires a human-readable reason in the state_history entry for each change of state.\nOODS Foundry keeps the setting. Your product checks the reason.\n",
        "default": false
      }
    ],
    "schema": {
      "status": {
        "type": "string",
        "required": true,
        "description": "Canonical lifecycle state derived from the states parameter. This is the single source\nof truth for the entity's current lifecycle position. Consumed by Colorized to resolve\nvisual tokens, and by view extensions to render StatusBadge and StatusTimeline.\n",
        "validation": {
          "enumFromParameter": "states"
        }
      },
      "state_history": {
        "type": "StateTransition[]",
        "required": false,
        "description": "Chronological log of state transitions. Each entry records the before/after states,\ntimestamp, and (when governance is enabled) the actor, reason, and transition metadata.\nRendered by StatusTimeline in the detail and timeline views.\n\nEntry structure:\n  - from: string (previous state)\n  - to: string (new state)\n  - timestamp: ISO 8601 datetime\n  - actor_id: string (user/system who triggered the transition, optional)\n  - reason: string (human-readable justification, required when requireTransitionReason is true)\n  - transition_metadata: Record<string, unknown> (arbitrary context, optional)\n\nEvery recorded change can name who acted, who it acted for and who approved it. All optional,\nfollowing Relationship's source_id/source_name pattern; only a *_name names a party, and an entry that names\nno one renders as it always has:\n  - actor_name: string (who acted, as shown: \"Billing Agent\")\n  - actor_kind: string (person, agent or system: the Actor trait's kinds)\n  - on_behalf_of_name / on_behalf_of_id: string (the person or organization it acted for)\n  - approved_by_name / approved_by_id: string (who approved the change, when someone did)\nStatusTimeline then reads \"Billing Agent for Tidewater Co-op · approved by Ruth Adeyemi\".\n\nA change someone approved can also say which approval it belongs to and what level of yes it was. Both\noptional; the id stays in the record's data, a pointer and not a link, and an entry without them renders as it\nalways has:\n  - approval_id: string (the Approval record the yes is kept in)\n  - approval_level: string (the level of yes, one of the levels the product declares: \"approval\")\nStatusTimeline then reads \"Billing Agent for Tidewater Co-op · approved by Ruth Adeyemi (level: Approval)\".\n\nA change made as part of a task can also say which task it was. Both optional; the id stays in the record's\ndata, a pointer and not a link, and an entry without them renders as it always has:\n  - task_id: string (the Task record the change was made under)\n  - task_name: string (the task, as shown: \"Get INV-2026-0155 paid\")\nStatusTimeline then reads \"… · approved by Ruth Adeyemi (level: Approval) · task: Get INV-2026-0155 paid\".\n\nA change made under a grant, the standing yes an actor acts under for a person or organization, can also say\nwhich grant it was. Both optional; the id stays in the record's data, a pointer and not a link, and an entry\nwithout them renders as it always has:\n  - grant_id: string (the Grant record the change was made under)\n  - grant_name: string (the grant, as shown: \"Resend returned transfers\")\nStatusTimeline names the grant after any approval and before the task: \"Billing Agent for Tidewater Co-op ·\ngrant: Resend returned transfers\".\n",
        "default": []
      },
      "allowed_transitions": {
        "type": "string[]",
        "required": false,
        "description": "Materialized list of the next states the product allows from the current status, written\nby the product from the transitionRules parameter. When transitionRules is null (open model),\nthis contains all states except the current one. The detail page's StatusTimeline lists it\nwhen the record holds it. A generated StatusSelector reads transitionRules instead: it offers the\ncurrent state and the moves the order allows (every state where no order is declared).\n",
        "default": []
      }
    },
    "semantics": {
      "status": {
        "semantic_type": "status.state",
        "token_mapping": "tokenMap(status.state.*)",
        "ui_hints": {
          "component": "StatusBadge",
          "showIcon": true
        }
      },
      "state_history": {
        "semantic_type": "timeline.state_transition",
        "token_mapping": "tokenMap(timeline.status.*)",
        "ui_hints": {
          "component": "StatusTimeline",
          "collapseWhenEmpty": true
        }
      },
      "allowed_transitions": {
        "semantic_type": "status.navigation",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "StatusSelector",
          "description": "The next states the product allows, as the product writes them; listed on the detail page, never used to disable an option."
        }
      }
    },
    "tokens": {
      "status.state.default.bg": "var(--status-neutral-bg)",
      "status.state.default.text": "var(--status-neutral-text)",
      "status.timeline.connector": "var(--border-subtle)",
      "status.timeline.node.bg": "var(--sys-surface-raised)",
      "status.timeline.node.border": "var(--sys-border-default)",
      "status.timeline.actor.text": "var(--sys-text-secondary)",
      "status.timeline.reason.text": "var(--sys-text-tertiary)",
      "status.timeline.reason.bg": "var(--sys-surface-neutral)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-10-12",
      "updated": "2026-11-16",
      "owners": [
        "Design team",
        "Engineering team"
      ],
      "maturity": "stable",
      "composedBy": {
        "count": 18,
        "notable": [
          "User",
          "Subscription",
          "Product",
          "Order",
          "Organization",
          "Article"
        ]
      },
      "accessibility": {
        "keyboard": "StatusSelector is a labelled native select: arrow keys move through the states it offers, the\ncurrent state and the moves the declared order allows (every state where none is declared). It\ndisables none.\n",
        "screenreader": "StatusBadge announces the current state (\"Status: Active\"). StateTransitionEvent entries\nannounce from-state, to-state, actor, and reason.\n"
      },
      "regionsUsed": [
        "list",
        "detail",
        "form",
        "card"
      ],
      "examples": [
        "Subscription",
        "Project Workflow",
        "Order",
        "User",
        "Invoice"
      ],
      "governanceExamples": [
        {
          "name": "Subscription lifecycle",
          "transitionRules": {
            "future": [
              "trialing",
              "active",
              "terminated"
            ],
            "trialing": [
              "active",
              "terminated"
            ],
            "active": [
              "paused",
              "pending_cancellation",
              "past_due",
              "terminated"
            ],
            "paused": [
              "active",
              "terminated"
            ],
            "pending_cancellation": [
              "active",
              "terminated"
            ],
            "past_due": [
              "active",
              "unpaid",
              "terminated"
            ],
            "unpaid": [
              "terminated"
            ],
            "terminated": []
          },
          "requireTransitionReason": true
        },
        {
          "name": "Content publishing",
          "transitionRules": {
            "draft": [
              "review"
            ],
            "review": [
              "draft",
              "published"
            ],
            "published": [
              "archived"
            ],
            "archived": [
              "draft"
            ]
          },
          "requireTransitionReason": false
        }
      ],
      "references": [
        "Trait Engine Spec v0.1 section 2",
        "objects/provenance.v1.json#/references/ref-ca663a7c5731 — tone resolution for Colorized integration",
        "objects/provenance.v1.json#/references/ref-be33a98177f7 — domain status mapping"
      ]
    },
    "objects": [
      "Agent",
      "Approval",
      "Article",
      "Closure",
      "Grant",
      "Media",
      "Organization",
      "Product",
      "Relationship",
      "Subscription",
      "Task",
      "Transaction",
      "User"
    ],
    "source": "traits/lifecycle/Stateful.trait.yaml"
  },
  "Statusable": {
    "name": "Statusable",
    "version": "1.0.0",
    "description": "Semantic status presentation layer that maps business statuses to visual tones,\ndesign tokens, and badge/banner rendering. Statusable owns the status registry\npattern: a domain-scoped lookup table that translates raw status strings into\nconsistent visual output (tone, label, icon, token sets).\n\nDISTINCT from Stateful — Stateful governs state machine transitions and guards;\nStatusable governs how status LOOKS. Statusable is the bridge between data-layer\nstate and the component layer (Badge, Banner, StatusBadge).\n\nCore concepts:\n- Status Registry: Map<domain, Map<status, StatusPresentation>>\n- Tone System: Six semantic tones (neutral, info, accent, success, warning, critical)\n- Token Resolution: --cmp-status-{tone}-{surface|border|text} CSS variables\n- Domain Scoping: Each domain (subscription, invoice, ticket, etc.) has its own status map\n- Emphasis Variants: badge.subtle / badge.solid, banner.subtle / banner.solid",
    "category": "visual",
    "tags": [
      "status",
      "presentation",
      "registry",
      "badge",
      "banner",
      "tone",
      "semantic",
      "saas"
    ],
    "contexts": [
      "detail",
      "form",
      "list",
      "timeline"
    ],
    "viewExtensions": [
      {
        "component": "StatusBadge",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "statusField": "status",
          "domainField": "domain",
          "emphasis": "subtle",
          "showIcon": true
        }
      },
      {
        "component": "StatusBadge",
        "context": "detail",
        "position": "main",
        "priority": 80,
        "props": {
          "statusField": "status",
          "domainField": "domain",
          "emphasis": "subtle",
          "showIcon": true
        }
      },
      {
        "component": "Banner",
        "context": "detail",
        "position": "top",
        "priority": 90,
        "props": {
          "statusField": "status",
          "domainField": "domain",
          "emphasis": "subtle",
          "showIcon": true
        }
      },
      {
        "component": "StatusBadge",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "statusField": "status",
          "domainField": "domain",
          "emphasis": "subtle",
          "readOnly": true
        }
      },
      {
        "component": "StatusBadge",
        "context": "timeline",
        "position": null,
        "priority": null,
        "props": {
          "statusField": "status",
          "domainField": "domain",
          "emphasis": "subtle",
          "showIcon": true,
          "compact": true
        }
      }
    ],
    "parameters": [
      {
        "name": "domains",
        "type": "string[]",
        "required": true,
        "description": "Domain identifiers whose statuses this object participates in.\nEach domain resolves to a scoped status map in the registry\n(e.g., \"subscription\", \"invoice\", \"ticket\", \"user\").\n",
        "default": [
          "subscription"
        ]
      },
      {
        "name": "toneAliases",
        "type": "Record<string, StatusTone>",
        "required": false,
        "description": "Custom alias map for inferring tones from token path segments.\nMerged with built-in aliases (info, positive→success, danger→critical, etc.).\nKeys are token path segments; values are canonical StatusTone values.\n",
        "default": {}
      },
      {
        "name": "defaultTone",
        "type": "StatusTone",
        "required": false,
        "description": "Fallback tone applied when a status is not found in the registry\nor when tone inference from token paths yields no match.\n",
        "default": "neutral",
        "validation": {
          "enum": [
            "neutral",
            "info",
            "accent",
            "success",
            "warning",
            "critical"
          ]
        }
      }
    ],
    "schema": {
      "status": {
        "type": "string",
        "required": true,
        "description": "Raw business status string (e.g., \"active\", \"past_due\", \"unpaid\").\nResolved against the domain's status map to derive presentation data.\n"
      },
      "domain": {
        "type": "StatusDomain",
        "required": true,
        "description": "Domain scope for registry lookup. Determines which status map is consulted\n(e.g., \"subscription\" statuses differ from \"invoice\" statuses).\n",
        "validation": {
          "enumFromParameter": "domains"
        }
      },
      "tone": {
        "type": "StatusTone",
        "required": false,
        "description": "Semantic tone derived from the registry or inferred from token paths.\nOne of: neutral, info, accent, success, warning, critical.\nFalls back to the defaultTone parameter when unresolvable.\n",
        "validation": {
          "enum": [
            "neutral",
            "info",
            "accent",
            "success",
            "warning",
            "critical"
          ]
        }
      },
      "badge_tokens": {
        "type": "StatusTokenVariants",
        "required": false,
        "description": "Resolved badge token sets with subtle and solid emphasis variants.\nEach variant contains { background, border, foreground } CSS variable references.\nStructure: { subtle: StatusTokenSet, solid: StatusTokenSet }\n"
      },
      "banner_tokens": {
        "type": "StatusTokenVariants",
        "required": false,
        "description": "Resolved banner token sets with subtle and solid emphasis variants.\nSubtle banners use domain-specific tokens when available; solid banners\nuse the tone-based component token set.\nStructure: { subtle: StatusTokenSet, solid: StatusTokenSet }\n"
      }
    },
    "semantics": {
      "status": {
        "semantic_type": "status.presentation.status",
        "token_mapping": "tokenMap(status.registry.*)",
        "ui_hints": {
          "component": "StatusBadge",
          "registryLookup": "getStatusPresentation(domain, status)"
        }
      },
      "domain": {
        "semantic_type": "status.presentation.domain",
        "token_mapping": "tokenMap(status.domains.*)",
        "ui_hints": {
          "component": "DomainSelector",
          "scopedTo": "domains"
        }
      },
      "tone": {
        "semantic_type": "status.presentation.tone",
        "token_mapping": "tokenMap(status.tone.*)",
        "ui_hints": {
          "component": "ToneBadge",
          "toneValues": [
            "neutral",
            "info",
            "accent",
            "success",
            "warning",
            "critical"
          ]
        }
      },
      "badge_tokens": {
        "semantic_type": "status.presentation.badge",
        "token_mapping": "tokenMap(cmp.status.{tone}.*)",
        "ui_hints": {
          "component": "Badge",
          "emphasisVariants": [
            "subtle",
            "solid"
          ]
        }
      },
      "banner_tokens": {
        "semantic_type": "status.presentation.banner",
        "token_mapping": "tokenMap(cmp.status.{tone}.*)",
        "ui_hints": {
          "component": "Banner",
          "emphasisVariants": [
            "subtle",
            "solid"
          ]
        }
      }
    },
    "tokens": {
      "cmp.status.neutral.surface": "var(--sys-surface-neutral)",
      "cmp.status.neutral.border": "var(--sys-border-neutral)",
      "cmp.status.neutral.text": "var(--sys-text-neutral)",
      "cmp.status.info.surface": "var(--sys-surface-info)",
      "cmp.status.info.border": "var(--sys-border-info)",
      "cmp.status.info.text": "var(--sys-text-info)",
      "cmp.status.accent.surface": "var(--sys-surface-accent)",
      "cmp.status.accent.border": "var(--sys-border-accent)",
      "cmp.status.accent.text": "var(--sys-text-accent)",
      "cmp.status.success.surface": "var(--sys-surface-success)",
      "cmp.status.success.border": "var(--sys-border-success)",
      "cmp.status.success.text": "var(--sys-text-success)",
      "cmp.status.warning.surface": "var(--sys-surface-warning)",
      "cmp.status.warning.border": "var(--sys-border-warning)",
      "cmp.status.warning.text": "var(--sys-text-warning)",
      "cmp.status.critical.surface": "var(--sys-surface-critical)",
      "cmp.status.critical.border": "var(--sys-border-critical)",
      "cmp.status.critical.text": "var(--sys-text-critical)",
      "cmp.banner.background": "var(--sys-surface-raised)",
      "cmp.banner.border": "var(--sys-border-default)",
      "cmp.banner.text": "var(--sys-text-default)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2026-02-28",
      "owners": [
        "Design team",
        "Engineering team"
      ],
      "maturity": "experimental",
      "accessibility": {
        "keyboard": "Badge and Banner elements are not interactive; no keyboard handling required.",
        "screenreader": "StatusBadge announces status label and tone as a live region.\nBanner uses role=\"status\" with aria-live=\"polite\" for critical/warning tones.\n"
      },
      "regionsUsed": [
        "list",
        "detail",
        "form",
        "timeline"
      ],
      "examples": [
        "Subscription",
        "Invoice",
        "Ticket",
        "User"
      ],
      "references": [
        "objects/provenance.v1.json#/references/ref-ca663a7c5731 — StatusPresentation, StatusTone, tone inference, domain maps",
        "objects/provenance.v1.json#/references/ref-24923e661958 — 7 sub-stories across 5 domains",
        "objects/provenance.v1.json#/references/ref-be33a98177f7 — domain status token map consumed by registry",
        "objects/provenance.v1.json#/references/ref-c373015a9045 — StatusableViewData, StatusTransitionEvent interfaces",
        "objects/provenance.v1.json#/references/ref-cc4cadcf82d5 — formatStatus, resolveDisplayName utilities"
      ]
    },
    "objects": [],
    "source": "traits/visual/Statusable.trait.yaml"
  },
  "Supersedable": {
    "name": "Supersedable",
    "version": "1.0.0",
    "description": "Records that one record replaces another of the same kind, and which of them still stands.\n\nSupersession is a self-referencing lineage, not a workflow: a record does not move through\nsupersession, it is replaced by a later record, and the pair stays readable afterwards. That is\nwhy it is its own trait rather than a Stateful state set — Stateful governs transitions between\nstates of one record, while Supersedable relates two records and keeps both.\n\nTwo stores already hold that shape and they record it from opposite ends. A decision store writes\nthe forward pointer (`superseded_by`, the replacement's id) beside a status of\nactive | superseded | archived | stale. OODS Foundry's own composition acceptances write the\nbackward pointer (`supersedes`, the acceptance this one replaced, with the time it was accepted)\nand leave the standing acceptance implicit. The trait therefore declares both pointers and a\n`recordedDirection` parameter naming which one the source of truth actually writes; the other is\nderived where the store can derive it and left absent where it cannot. An absent pointer means\nunknown, never \"nothing was superseded\".\n\nThe field is `supersession_status`, not `status`, so an object can carry its own lifecycle\nthrough Stateful and its supersession through this trait without the two colliding.",
    "category": "lifecycle",
    "tags": [
      "lifecycle",
      "supersession",
      "lineage",
      "provenance",
      "versioning"
    ],
    "contexts": [
      "card",
      "detail",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "StatusBadge",
        "context": "list",
        "position": "after",
        "priority": null,
        "props": {
          "statusField": "supersession_status",
          "emphasis": "subtle",
          "showIcon": false
        }
      },
      {
        "component": "StatusBadge",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "statusField": "supersession_status",
          "emphasis": "subtle",
          "showIcon": false
        }
      },
      {
        "component": "StatusBadge",
        "context": "detail",
        "position": "main",
        "priority": 70,
        "props": {
          "statusField": "supersession_status",
          "emphasis": "subtle",
          "showIcon": false
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 69,
        "props": {
          "field": "superseded_by"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 68,
        "props": {
          "field": "supersedes"
        }
      },
      {
        "component": "Text",
        "context": "detail",
        "position": "main",
        "priority": 67,
        "props": {
          "field": "supersession_reason"
        }
      }
    ],
    "parameters": [
      {
        "name": "states",
        "type": "string[]",
        "required": true,
        "description": "The supersession states this store can actually write. A store that only ever distinguishes a\nstanding record from a replaced one declares two; a decision store declares four because it also\nretires a decision without replacing it (archived) and marks one as needing review (stale).\n",
        "default": [
          "active",
          "superseded",
          "archived",
          "stale"
        ]
      },
      {
        "name": "initialState",
        "type": "string",
        "required": true,
        "description": "The state a newly recorded entry holds before anything replaces it.",
        "default": "active",
        "validation": {
          "enumFromParameter": "states"
        }
      },
      {
        "name": "recordedDirection",
        "type": "string",
        "required": true,
        "description": "Which pointer the source of truth writes: `forward` stores `superseded_by` on the record that\nwas replaced (a decision store), `backward` stores `supersedes` on the record that replaced it (OODS Foundry's\ncomposition acceptances), `both` stores each. The pointer that is not recorded is derived only\nwhen the store can derive it, and is otherwise absent — the screen says unknown rather than\nclaiming the record supersedes nothing.\n",
        "default": "forward",
        "validation": {
          "enum": [
            "forward",
            "backward",
            "both"
          ]
        }
      },
      {
        "name": "supersededLabel",
        "type": "string",
        "required": false,
        "description": "Visible wording for a record that has been replaced, so the screen never relies on colour alone.",
        "default": "Superseded"
      }
    ],
    "schema": {
      "supersession_status": {
        "type": "string",
        "required": true,
        "default": "active",
        "description": "Whether this record still stands. Named apart from Stateful's `status` so an object can carry\nboth a lifecycle and a supersession lineage.\n"
      },
      "superseded_by": {
        "type": "string",
        "required": false,
        "description": "Identifier of the record that replaced this one. Present when the store records the forward\npointer. Absent means not replaced, or not known — the two are distinguished by\nsupersession_status, never by the pointer alone.\n"
      },
      "supersedes": {
        "type": "string",
        "required": false,
        "description": "Identifier of the record this one replaced. Present when the store records the backward\npointer. Never inferred from ordering.\n"
      },
      "superseded_at": {
        "type": "datetime?",
        "required": false,
        "description": "When the replacement happened, when the store records it. A store that does not record it leaves\nit absent rather than borrowing the replacement's creation time.\n"
      },
      "supersession_reason": {
        "type": "string",
        "required": false,
        "description": "Why the record was replaced, when the store carries a reason.",
        "validation": {
          "maxLength": 500
        }
      }
    },
    "semantics": {
      "supersession_status": {
        "semantic_type": "lifecycle.supersession.state",
        "token_mapping": "tokenMap(lifecycle.supersession.*)",
        "ui_hints": {
          "component": "StatusBadge",
          "showIcon": false
        }
      },
      "superseded_by": {
        "semantic_type": "lifecycle.supersession.replacement",
        "token_mapping": "tokenMap(lifecycle.supersession.link)",
        "ui_hints": {
          "component": "Text"
        }
      },
      "supersedes": {
        "semantic_type": "lifecycle.supersession.replaced",
        "token_mapping": "tokenMap(lifecycle.supersession.link)",
        "ui_hints": {
          "component": "Text"
        }
      },
      "superseded_at": {
        "semantic_type": "lifecycle.supersession.timestamp",
        "token_mapping": "tokenMap(lifecycle.supersession.timestamp)",
        "ui_hints": {
          "component": "RelativeTimestamp"
        }
      },
      "supersession_reason": {
        "semantic_type": "lifecycle.supersession.reason",
        "token_mapping": "tokenMap(lifecycle.supersession.reason)",
        "ui_hints": {
          "component": "Text",
          "maxLength": 500
        }
      }
    },
    "tokens": {
      "lifecycle.supersession.active.bg": "var(--sys-status-success-surface)",
      "lifecycle.supersession.active.text": "var(--sys-status-success-text)",
      "lifecycle.supersession.superseded.bg": "var(--sys-surface-neutral)",
      "lifecycle.supersession.superseded.text": "var(--sys-text-secondary)",
      "lifecycle.supersession.link.text": "var(--text-strong)",
      "lifecycle.supersession.timestamp.text": "var(--text-subtle)",
      "lifecycle.supersession.reason.text": "var(--text-default)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2026-09-16",
      "updated": "2026-09-16",
      "owners": [
        "Lifecycle team"
      ],
      "maturity": "alpha",
      "accessibility": {
        "keyboard": "Supersession adds no interactive control of its own; the pointer renders as text beside the\nrecord it names.\n",
        "screenreader": "The supersession state is announced as visible text through StatusBadge, not by colour alone, and\nthe pointer fields read as \"Superseded by <id>\" / \"Supersedes <id>\".\n"
      },
      "regionsUsed": [
        "list",
        "card",
        "detail"
      ],
      "examples": [
        "Decision"
      ],
      "references": [
        "objects/provenance.v1.json#/references/ref-d6670b6a0f62 — CompositionAcceptance.supersedes, the backward-recording consumer",
        "A CMOS store's strategic_decisions.superseded_by + status, the forward-recording consumer"
      ]
    },
    "objects": [],
    "source": "traits/lifecycle/Supersedable.trait.yaml"
  },
  "Taggable": {
    "name": "Taggable",
    "version": "2.0.0",
    "description": "Adds configurable tag management with guardrails for custom authoring, taxonomy alignment,\nand tag governance. Taggable supports both open tagging (user-defined) and controlled\nvocabularies (allow-list), with optional moderation workflows for tag quality control.\n\nTags are first-class metadata in OODS — they drive discovery, filtering, and cross-object\nrelationships. The trait provides per-tag governance metadata (creator, creation date,\nusage count) for taxonomy health monitoring, and optional synonym resolution to prevent\ntag fragmentation (e.g., \"javascript\" and \"js\" resolve to the same canonical tag).",
    "category": "behavioral",
    "tags": [
      "tagging",
      "classification",
      "metadata",
      "discovery",
      "governance",
      "taxonomy"
    ],
    "contexts": [
      "card",
      "detail",
      "form",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "TagPills",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "field": "tags",
          "maxVisible": 3,
          "overflowLabel": "+{{ tag_count }}"
        }
      },
      {
        "component": "TagSummary",
        "context": "detail",
        "position": "top",
        "priority": null,
        "props": {
          "field": "tags",
          "countField": "tag_count"
        }
      },
      {
        "component": "TagInput",
        "context": "form",
        "position": "top",
        "priority": null,
        "props": {
          "field": "tags",
          "maxTagsParameter": "maxTags",
          "allowCustomParameter": "allowCustomTags",
          "allowListParameter": "allowedTags",
          "minLengthParameter": "tagMinLength",
          "maxLengthParameter": "tagMaxLength",
          "synonymParameter": "synonymResolution"
        }
      },
      {
        "component": "TagPills",
        "context": "card",
        "position": "after",
        "priority": null,
        "props": {
          "field": "tags",
          "maxVisible": 3,
          "overflowLabel": "+{{ tag_count }}"
        }
      }
    ],
    "parameters": [
      {
        "name": "maxTags",
        "type": "number",
        "required": false,
        "description": "Maximum number of tags that can be attached to an entity.",
        "default": 10,
        "validation": {
          "minimum": 1,
          "maximum": 64
        }
      },
      {
        "name": "allowCustomTags",
        "type": "boolean",
        "required": false,
        "description": "Whether editors may author tags outside of the approved allow list. When false,\nonly tags from allowedTags are permitted. When true with allowedTags present,\nthe allow list serves as suggestions rather than a constraint.\n",
        "default": true
      },
      {
        "name": "allowedTags",
        "type": "string[]",
        "required": false,
        "description": "Curated allow list of permitted tags. Behavior depends on allowCustomTags:\n- allowCustomTags=false: Only these tags are permitted (strict mode).\n- allowCustomTags=true: These tags appear as suggestions in TagInput autocomplete.\n",
        "validation": {
          "minItems": 1,
          "uniqueItems": true,
          "items": {
            "minLength": 1,
            "maxLength": 64
          }
        }
      },
      {
        "name": "caseSensitive",
        "type": "boolean",
        "required": false,
        "description": "Whether tag comparisons should treat casing as significant.",
        "default": false
      },
      {
        "name": "tagMinLength",
        "type": "number",
        "required": false,
        "description": "Minimum character length for a tag value. Prevents single-character or empty tags\nthat add noise to the taxonomy. Applied to both custom and allow-list tags.\n",
        "default": 2,
        "validation": {
          "minimum": 1,
          "maximum": 32
        }
      },
      {
        "name": "tagMaxLength",
        "type": "number",
        "required": false,
        "description": "Maximum character length for a tag value. Prevents excessively long tags that\nbreak UI layouts and reduce readability.\n",
        "default": 64,
        "validation": {
          "minimum": 1,
          "maximum": 256
        }
      },
      {
        "name": "allowTagModeration",
        "type": "boolean",
        "required": false,
        "description": "When true, newly created custom tags enter a \"pending\" state and require approval\nfrom a moderator before becoming visible to other users. Tags from the allowedTags\nlist are pre-approved and skip moderation. Useful for public-facing taxonomies where\ntag quality matters.\n",
        "default": false
      },
      {
        "name": "synonymResolution",
        "type": "string",
        "required": false,
        "description": "Controls how synonym/alias tags are handled:\n- none: No synonym resolution. Tags are stored as-is.\n- suggest: When a tag matches a known synonym, the UI suggests the canonical form\n  but allows the original.\n- auto: Tags matching known synonyms are automatically replaced with the canonical\n  form on save. Requires a synonym map in tag_metadata.\n",
        "default": "none",
        "validation": {
          "enum": [
            "none",
            "suggest",
            "auto"
          ]
        }
      }
    ],
    "schema": {
      "tags": {
        "type": "string[]",
        "required": false,
        "description": "Ordered list of tags assigned to the entity.",
        "default": [],
        "validation": {
          "maxItems": 64
        }
      },
      "tag_count": {
        "type": "number",
        "required": true,
        "description": "Computed number of tags assigned to the entity.",
        "default": 0,
        "validation": {
          "minimum": 0
        }
      },
      "tag_metadata": {
        "type": "object[]",
        "required": false,
        "description": "Per-tag governance metadata. Each entry corresponds to a tag in the tags array and\ntracks provenance and usage for taxonomy health monitoring.\n\nEntry structure:\n  - tag: string (the tag value, matches entry in tags array)\n  - created_at: ISO 8601 datetime\n  - created_by: string (user ID or \"system\" for allow-list tags)\n  - usage_count: number (how many entities use this tag, computed)\n  - moderation_status: \"approved\" | \"pending\" | \"rejected\" (when allowTagModeration is true)\n  - canonical_form: string (resolved synonym target, when synonymResolution is enabled)\n",
        "default": []
      }
    },
    "semantics": {
      "tags": {
        "semantic_type": "taxonomy.tag.collection",
        "token_mapping": "tokenMap(taxonomy.tag.*)",
        "ui_hints": {
          "component": "TagCollection",
          "allowCreateParameter": "allowCustomTags",
          "allowListParameter": "allowedTags",
          "caseSensitiveParameter": "caseSensitive"
        }
      },
      "tag_count": {
        "semantic_type": "metric.collection.count",
        "token_mapping": "tokenMap(taxonomy.tag.count)",
        "ui_hints": {
          "component": "MetricBadge",
          "format": "integer"
        }
      },
      "tag_metadata": {
        "semantic_type": "taxonomy.tag.governance",
        "token_mapping": "computed",
        "ui_hints": {
          "component": "TagGovernancePanel",
          "description": "Admin panel for reviewing tag health, moderation queue, and synonym resolution."
        }
      }
    },
    "tokens": {
      "taxonomy.tag.chip.bg": "var(--surface-tag-bg)",
      "taxonomy.tag.chip.text": "var(--surface-tag-text)",
      "taxonomy.tag.chip.border": "var(--sys-border-default)",
      "taxonomy.tag.chip.hover.bg": "var(--sys-surface-hover)",
      "taxonomy.tag.chip.pending.bg": "var(--sys-status-warning-surface)",
      "taxonomy.tag.chip.pending.text": "var(--sys-status-warning-text)",
      "taxonomy.tag.summary.count": "var(--text-subtle)",
      "taxonomy.tag.input.border": "var(--sys-border-default)",
      "taxonomy.tag.input.focus.border": "var(--sys-border-focus)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-10-12",
      "updated": "2026-02-28",
      "owners": [
        "Design team",
        "Taxonomy team"
      ],
      "maturity": "stable",
      "accessibility": {
        "keyboard": "TagInput supports full keyboard navigation:\n- Type to filter/create tags, Enter to confirm\n- Backspace to remove the last tag when input is empty\n- Arrow keys to navigate autocomplete suggestions\n- Escape to dismiss the autocomplete dropdown\n- Tab to move focus out of the tag input\nTagPills in list view are not interactive (display only).\n",
        "screenreader": "Tag list is announced as a group with count (e.g., \"Tags: 3 items\").\nEach tag chip is announced individually. When moderation is enabled,\npending tags are announced with their moderation status.\nTagInput announces available suggestion count on keystroke.\n"
      },
      "regionsUsed": [
        "list",
        "detail",
        "form",
        "card"
      ],
      "examples": [
        "Knowledge Article",
        "Incident",
        "Product",
        "Media"
      ],
      "references": [
        "Trait Engine Spec v0.1 section 2"
      ]
    },
    "objects": [
      "Organization",
      "Relationship",
      "User"
    ],
    "source": "traits/behavioral/Taggable.trait.yaml"
  },
  "Timestampable": {
    "name": "Timestampable",
    "version": "1.0.1",
    "description": "Captures creation and update timestamps with configurable audit metadata for lifecycle tracking.",
    "category": "lifecycle",
    "tags": [
      "timestamp",
      "audit",
      "lifecycle",
      "metadata"
    ],
    "contexts": [
      "detail",
      "list"
    ],
    "viewExtensions": [
      {
        "component": "AuditTimeline",
        "context": "detail",
        "position": "bottom",
        "priority": null,
        "props": {
          "createdField": "created_at",
          "updatedField": "updated_at",
          "eventField": "last_event",
          "eventTimestampField": "last_event_at",
          "eventOptionsParameter": "recordedEvents"
        }
      },
      {
        "component": "RelativeTimestamp",
        "context": "list",
        "position": null,
        "priority": null,
        "props": {
          "field": "updated_at",
          "fallbackField": "created_at",
          "timezoneParameter": "timezone"
        }
      }
    ],
    "parameters": [
      {
        "name": "recordedEvents",
        "type": "string[]",
        "required": true,
        "description": "Canonical lifecycle events captured in the audit timeline.",
        "default": [
          "created",
          "updated",
          "deleted"
        ]
      },
      {
        "name": "timezone",
        "type": "string",
        "required": false,
        "description": "The time zone your product reads the record's times in. Screens show times in UTC, and a shown date-time says so, as a date-time input's label does.",
        "default": "UTC",
        "validation": {
          "enum": [
            "UTC",
            "LOCAL",
            "OFFSET"
          ]
        }
      },
      {
        "name": "allowNullUpdatedAt",
        "type": "boolean",
        "required": false,
        "description": "Whether updated_at may be omitted when no mutations have occurred.",
        "default": true
      }
    ],
    "schema": {
      "created_at": {
        "type": "datetime",
        "required": true,
        "description": "Timestamp recording when the entity was first created."
      },
      "updated_at": {
        "type": "datetime",
        "required": false,
        "description": "Timestamp for the most recent modification, when available."
      },
      "last_event": {
        "type": "string",
        "required": true,
        "description": "Lifecycle event associated with the most recent timestamp mutation.",
        "validation": {
          "enumFromParameter": "recordedEvents"
        }
      },
      "last_event_at": {
        "type": "datetime",
        "required": false,
        "description": "Timestamp for the lifecycle event captured in last_event."
      }
    },
    "semantics": {
      "created_at": {
        "semantic_type": "audit.created_at",
        "token_mapping": "tokenMap(audit.created)",
        "ui_hints": {
          "component": "TimelineTimestamp",
          "timezoneParameter": "timezone"
        }
      },
      "updated_at": {
        "semantic_type": "audit.updated_at",
        "token_mapping": "tokenMap(audit.updated)",
        "ui_hints": {
          "component": "TimelineTimestamp",
          "timezoneParameter": "timezone",
          "allowNullParameter": "allowNullUpdatedAt"
        }
      },
      "last_event": {
        "semantic_type": "audit.event.type",
        "token_mapping": "tokenMap(audit.event.*)",
        "ui_hints": {
          "component": "AuditBadge",
          "parameterSource": "recordedEvents"
        }
      },
      "last_event_at": {
        "semantic_type": "audit.event.timestamp",
        "token_mapping": "tokenMap(audit.event.timestamp)",
        "ui_hints": {
          "component": "TimelineTimestamp",
          "timezoneParameter": "timezone"
        }
      }
    },
    "tokens": {
      "audit.created.badge.text": "var(--text-subtle)",
      "audit.updated.badge.text": "var(--text-subtle)",
      "audit.event.badge.bg": "var(--surface-muted)"
    },
    "dependencies": [],
    "metadata": {
      "created": "2025-10-16",
      "owners": [
        "Lifecycle team",
        "Platform team"
      ],
      "maturity": "stable",
      "accessibility": {
        "keyboard": "n/a",
        "screenreader": "Announces creation and last update information with lifecycle context."
      },
      "regionsUsed": [
        "detail",
        "list"
      ],
      "examples": [
        "User",
        "Organization",
        "Transaction"
      ],
      "references": [
        "Trait Engine Spec v0.1 §2"
      ]
    },
    "objects": [
      "Agent",
      "Approval",
      "Article",
      "Closure",
      "Grant",
      "Invoice",
      "Media",
      "Organization",
      "Product",
      "Relationship",
      "Subscription",
      "Task",
      "Transaction",
      "Usage",
      "User"
    ],
    "source": "traits/lifecycle/Timestampable.trait.yaml"
  }
}
