@unified-product-graph/core 0.30.0 → 0.31.0

package/dist/index.js

@@ -394,7 +394,7 @@ var UPG_DOMAINS = [
   {
     id: "program_mgmt",
     label: "Program Management",
-    description: "Coordinating delivery across teams and timelines. Programs are the highest container. Projects break programs down. Milestones mark key dates. Risk registers track threats to delivery. Change requests manage scope changes. Deliverables define what ships. Resource allocations assign effort. Status reports communicate progress. Connects Product Specification (what to deliver) to Team & Organisation (who delivers).",
+    description: "Coordinating delivery across teams and timelines. Programs are the highest container. Projects break programs down. Milestones mark key dates, and hang from either a project or, where a product owns the date outright with no program above it, from the product itself. Risk registers track threats to delivery. Change requests manage scope changes. Deliverables define what ships. Resource allocations assign effort. Status reports communicate progress. Connects Product Specification (what to deliver) to Team & Organisation (who delivers).",
     types: [
       "program",
       "project",
@@ -490,8 +490,8 @@ var UPG_DOMAINS = [
   {
     id: "workspace",
     label: "Workspace",
-    description: "Spatial thinking spaces for arranging entities, debating decisions, and committing to the graph. Workspaces are transient canvases that sit alongside all other domains, letting you compose and explore relationships before they become permanent graph structure. A framework exercise is a structured workspace: one run of a framework (MoSCoW, RICE, Kano, \u2026) applied to a chosen set of entities, with each entity's result recorded on the exercise-to-entity edge rather than the entity itself.",
-    types: ["workspace", "framework_exercise"]
+    description: "Spatial thinking spaces for arranging entities, debating decisions, and committing to the graph. Workspaces are transient canvases that sit alongside all other domains, letting you compose and explore relationships before they become permanent graph structure. A framework exercise is a structured workspace: one run of a framework (MoSCoW, RICE, Kano, \u2026) applied to a chosen set of entities, with each entity's result recorded on the exercise-to-entity edge rather than the entity itself. A composition is the durable other half: a named, published view assembled from a canvas, with a stable slug people link to and a revision history, whose frozen arrangement holds pointers rather than copied content.",
+    types: ["workspace", "framework_exercise", "composition"]
   },
   {
     id: "foundations",
@@ -978,7 +978,8 @@ var UPG_ENTITY_META = [
   { name: "partner_revenue_share", type_id: "ent_312", maturity: "stable", since: "0.1.0" },
   // ── Workspace ──
   { name: "workspace", type_id: "ent_328", maturity: "proposed", since: "0.2.0" },
-  { name: "framework_exercise", type_id: "ent_350", maturity: "proposed", since: "0.8.4" }
+  { name: "framework_exercise", type_id: "ent_350", maturity: "proposed", since: "0.8.4" },
+  { name: "composition", type_id: "ent_361", maturity: "proposed", since: "0.31.0" }
 ];
 var DEFERRED_PROPOSED_BY_CONTRACT = {
   // user_story (UPG-571) and experiment_run (UPG-664) graduated to stable in
@@ -1072,6 +1073,24 @@ var CONFIGURATION_QUALIFIER_EDGE_PROPERTY_SCHEMA = {
     required: ["axis", "values"]
   }
 };
+var WORKSPACE_ARRANGEMENT_EDGE_PROPERTY_SCHEMA = {
+  x: {
+    type: "number",
+    description: "Horizontal canvas coordinate of the card, in the canvas's own units. Expected on every arrangement: a placement without coordinates is not a placement."
+  },
+  y: {
+    type: "number",
+    description: "Vertical canvas coordinate of the card, in the canvas's own units. Expected on every arrangement: a placement without coordinates is not a placement."
+  },
+  expanded: {
+    type: "boolean",
+    description: "Whether the card is drawn expanded rather than collapsed. Presentation state that survives a reload, unlike selection."
+  },
+  frame_id: {
+    type: "string",
+    description: "Id of the canvas frame this card sits inside. The frame itself is opaque furniture and lives in `workspace.properties.canvas.frames`, so this names a bag member rather than a graph node."
+  }
+};
 var UPG_EDGE_CATALOG = {
   // ── Part 1: Core Narrative Spine (Ring 1) ──────────────────────────────────
   // 1.1 User Domain
@@ -1968,7 +1987,40 @@ var UPG_EDGE_CATALOG = {
   // real edge, not just a string property — the domain's own anti-pattern is
   // "version prompts like code".
   prompt_version_supersedes_prompt_version: { forward_verb: "supersedes", reverse_verb: "superseded_by", classification: "semantic", source_type: "prompt_version", target_type: "prompt_version" },
+  // The TYPED subject edge. Kept alongside the polymorphic `eval_benchmark_measures_node`
+  // added in 0.31.0, on the same footing as `constraint_constrains_feature` beside
+  // `node_constrains_node`: reach for THIS one when the subject is a feature, and for the
+  // wildcard only when it is not. Two ways to say the same thing about a feature is the
+  // cost of the pair, and it is paid deliberately rather than by accident.
   eval_benchmark_measures_feature: { forward_verb: "measures", reverse_verb: "measured_by", classification: "cross-domain", source_type: "eval_benchmark", target_type: "feature" },
+  /*
+   * 0.31.0 — the benchmark SUBJECT, polymorphic.
+   *
+   * An eval measures a tool, a document, a check, an importer, a feature. Those
+   * are unrelated types, so the subject relation is genuinely wildcard-shaped and
+   * follows the decision-to-anything family (`decision_influences_node`).
+   *
+   * THE WIDTH IS OVER-WIDE, AND THAT IS ON THE LABEL RATHER THAN LAUNDERED.
+   * The decision family's warrant is that a decision really is about anything. A
+   * benchmark is not: it measures a MEASURABLE thing, and this edge will happily
+   * claim a benchmark can measure a persona, which is meaningless. It ships as the
+   * honest deferral it is — the alternative was minting typed edges for subject
+   * types the spec does not yet have, which would answer "what is a tool in the
+   * graph" as a side effect of building an eval harness. That question is a stated
+   * non-goal, and deferring it is the point of choosing the wildcard.
+   *
+   * Registered in UPG_POLYMORPHIC_EDGE_KEYS; Audit 05 errors on any wildcard that
+   * is not.
+   */
+  eval_benchmark_measures_node: { forward_verb: "measures", reverse_verb: "measured_by", classification: "semantic", source_type: "eval_benchmark", target_type: "node" },
+  /*
+   * 0.31.0 — the labeled corpus a benchmark draws its cases from.
+   *
+   * `ai_dataset` reused rather than a new `corpus` type minted (Q5, ratified): the
+   * existing type plus one join edge carries the need, and a corpus type would be
+   * minted only if that demonstrably failed. It has not.
+   */
+  eval_benchmark_draws_cases_from_ai_dataset: { forward_verb: "draws_cases_from", reverse_verb: "provides_cases_to", classification: "semantic", source_type: "eval_benchmark", target_type: "ai_dataset" },
   ai_guardrail_enforces_security_policy: { forward_verb: "enforces", reverse_verb: "enforced_by", classification: "cross-domain", source_type: "ai_guardrail", target_type: "security_policy" },
   model_comparison_informs_decision: { forward_verb: "informs", reverse_verb: "informed_by", classification: "cross-domain", source_type: "model_comparison", target_type: "decision" },
   ai_cost_tracker_feeds_cost_structure: { forward_verb: "feeds", reverse_verb: "fed_by", classification: "cross-domain", source_type: "ai_cost_tracker", target_type: "cost_structure" },
@@ -2006,6 +2058,23 @@ var UPG_EDGE_CATALOG = {
   agent_hook_triggers_ci_pipeline: { forward_verb: "triggers", reverse_verb: "triggered_by", classification: "cross-domain", source_type: "agent_hook", target_type: "ci_pipeline" },
   workflow_template_defines_agent_task: { forward_verb: "defines", reverse_verb: "defined_by", classification: "hierarchy", source_type: "workflow_template", target_type: "agent_task" },
   agent_definition_spawns_agent_task: { forward_verb: "spawns", reverse_verb: "spawned_by", classification: "hierarchy", source_type: "agent_definition", target_type: "agent_task" },
+  // The delegation bridge (tasks-workflows-2026-08 §5). Before this, the whole
+  // automation domain could reach product work only at coarse grain —
+  // `workflow_run_implements_initiative` (initiative), `agent_skill_extends_feature`
+  // (feature), `agent_session_creates_decision` (decision),
+  // `workflow_artifact_references_deliverable` (deliverable) — and NOTHING reached
+  // `task`, the atomic unit of product work that `feature_decomposes_into_task` /
+  // `epic_decomposes_into_task` make the delivery hierarchy's leaf. So "this agent
+  // work item IS the execution of that product task" was inexpressible, and a
+  // human-vs-agent assignee could not be read off the graph.
+  // Cross-domain: agent_task lives in `automation`, task in product delivery.
+  // NOT hierarchy — the agent_task does not CONTAIN the task; both are
+  // independently-parented work items (`workflow_template_defines_agent_task` /
+  // `agent_definition_spawns_agent_task` own the agent side, feature/epic the
+  // product side), and the delegation is a lateral reference between them.
+  // Verb `executes` mirrors the domain's own vocabulary (`workflow_template`
+  // is `executed_as` a run); reverse reads "this task is executed_by that agent task".
+  agent_task_executes_task: { forward_verb: "executes", reverse_verb: "executed_by", classification: "cross-domain", source_type: "agent_task", target_type: "task" },
   // ── Part 4: Scale Ring (Ring 4) ────────────────────────────────────────────
   // 4.1 Growth Domain
   product_measures_funnel: { forward_verb: "measures", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "product", target_type: "funnel" },
@@ -2356,6 +2425,25 @@ var UPG_EDGE_CATALOG = {
   product_managed_via_program: { forward_verb: "managed_via", reverse_verb: "manages", classification: "hierarchy", source_type: "product", target_type: "program" },
   program_contains_project: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "program", target_type: "project" },
   project_targets_milestone: { forward_verb: "targets", reverse_verb: "targeted_by", classification: "hierarchy", source_type: "project", target_type: "milestone" },
+  // Portfolio Phase 2 (ratified 2026-08-14): a milestone that a PRODUCT owns
+  // outright, with no program/project above it. `milestone` had exactly one
+  // inbound edge spec-wide (`project_targets_milestone`) and `project` was its
+  // only declared parent, so a portfolio-grain milestone — which names a
+  // product, not a project — was inexpressible. This is the 0.23.0 epic-twin
+  // precedent: an existing leaf type gains a second, SHALLOWER parent, and the
+  // name, verbs and classification are the deeper edge's, inherited unchanged
+  // rather than invented.
+  //
+  // The mediated path was checked and rejected, not overlooked. The relation IS
+  // reachable as product —managed_via→ program —contains→ project —targets→
+  // milestone, but at three hops (past the 1-2-hop threshold), and the hop count
+  // is not the real objection: mediation forces `program` and `project` nodes
+  // into existence that the source data does not have.
+  //
+  // NOT cross_product_eligible: a milestone belongs to the graph of the product
+  // that owns it. `UPG_VALID_CHILDREN.product` gains 'milestone' in step, which
+  // the hierarchy-orphan guard requires.
+  product_targets_milestone: { forward_verb: "targets", reverse_verb: "targeted_by", classification: "hierarchy", source_type: "product", target_type: "milestone" },
   project_produces_deliverable: { forward_verb: "produces", reverse_verb: "produced_by", classification: "hierarchy", source_type: "project", target_type: "deliverable" },
   program_tracked_via_risk_register: { forward_verb: "tracked_via", reverse_verb: "tracks", classification: "hierarchy", source_type: "program", target_type: "risk_register" },
   risk_register_contains_risk: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "risk_register", target_type: "risk" },
@@ -2502,6 +2590,50 @@ var UPG_EDGE_CATALOG = {
   // node) has no schema mechanism yet — deliberately deferred, see the WS3
   // proposal doc, ripple map "surprises" #3.
   workspace_produced_node: { forward_verb: "produced", reverse_verb: "produced_in", classification: "causal", source_type: "workspace", target_type: "node" },
+  // Canvas arrangement: which entities are ON a workspace, and where. This is
+  // the edge `WorkspaceProperties`' docstring promised for months without the
+  // catalog having it; the promise is now true.
+  //
+  // Polymorphic per the enum-vs-polymorphism ADR (2026-06-16), on all three
+  // arms: universality holds (any entity can be dragged onto a canvas, with no
+  // principled stopping point), constraint value is nil (nobody could defend
+  // "you may arrange features but not personas"), and there is NO STRUCTURAL
+  // ROLE. That third arm is load-bearing rather than decorative.
+  // `classification: 'cross-domain'` is therefore mandatory, not cosmetic: it
+  // keeps the edge out of `UPG_VALID_CHILDREN` and `resolveContainmentEdge`, so
+  // `get_tree` never walks it and a canvas placement can never masquerade as
+  // containment. An arranged node keeps its real containment parent. Same
+  // posture as `framework_exercise_includes_node`.
+  //
+  // The alternative was putting the whole canvas snapshot in one opaque node
+  // property, which is cheaper and loses. A node id inside a blob is a foreign
+  // key held as a scalar (the exact thing P14 forbids), the placed entities
+  // become invisible to `get_node` and `query`, and a deleted node leaves a
+  // stale reference that `repair_dangling_edges` cannot see. As an edge, that
+  // guard is inherited for free. Only the furniture with no graph referent
+  // stays opaque, in `workspace.properties.canvas`.
+  //
+  // NOT cross_product_eligible: deliberate scope limit mirroring the WS3
+  // anchors, not an oversight.
+  workspace_arranges_node: { forward_verb: "arranges", reverse_verb: "arranged_in", classification: "cross-domain", source_type: "workspace", target_type: "node", carries_properties: true, property_schema: WORKSPACE_ARRANGEMENT_EDGE_PROPERTY_SCHEMA },
+  // What a published composition SHOWS. Passes the same three-arm ADR test the
+  // same way, and carries no properties: a focus is a bare reference.
+  //
+  // It earns its place by making a composition legible to a tool that cannot
+  // parse the publishing tool's URLs. "Which published views show this
+  // persona?" is a LEARN question the graph exists to answer, and the edge is
+  // what makes a composition's graph references repairable when a focused node
+  // is deleted. Adding it in a later release would be a second blast-radius
+  // event on the same track.
+  //
+  // POPULATION IS BEST-EFFORT and an empty focus set is VALID: a composition
+  // whose member hrefs the writing tool cannot resolve to node ids is still a
+  // well-formed composition. That keeps the spec complete without blocking on
+  // app work, and it is why no check fires on an unfocused composition.
+  //
+  // NOT cross_product_eligible: a portfolio-level composition spanning several
+  // product graphs is conceivable but unevidenced. Same YAGNI call as above.
+  composition_focuses_node: { forward_verb: "focuses", reverse_verb: "focused_in", classification: "cross-domain", source_type: "composition", target_type: "node" },
   // ── P14 edges (replacing foreign-key properties) ─────────────────────────
   feature_addresses_job: { forward_verb: "addresses", reverse_verb: "addressed_by", classification: "cross-domain", source_type: "feature", target_type: "job" },
   feature_drives_key_result: { forward_verb: "drives", reverse_verb: "driven_by", classification: "cross-domain", source_type: "feature", target_type: "key_result" },
@@ -3546,6 +3678,9 @@ var UPG_POLYMORPHIC_EDGE_KEYS = [
   "framework_exercise_includes_node",
   // Universal classification (any node classified against a classification_value)
   "node_classified_as_classification_value",
+  // Benchmark subject (0.31.0): an eval measures a tool, a doc, a check, an
+  // importer, a feature. Over-wide by admission — see the definition's comment.
+  "eval_benchmark_measures_node",
   // Work-item issue links (0.20.0): endpoint-polymorphic over the work-item set
   // {feature, epic, user_story, task, bug}. The `work_item_` key names the
   // intended semantic domain; the endpoints are the `node` wildcard.
@@ -3554,7 +3689,12 @@ var UPG_POLYMORPHIC_EDGE_KEYS = [
   "work_item_duplicates_work_item",
   // Workspace provenance (WS3, 2026-07-05): a workspace can produce any
   // entity type arranged in it. Widened from workspace_produced_decision.
-  "workspace_produced_node"
+  "workspace_produced_node",
+  // Canvas arrangement and published-view focus: any entity can be dragged
+  // onto a canvas or shown in a published view, and neither carries a
+  // structural role, so both collapse polymorphic rather than enumerating.
+  "workspace_arranges_node",
+  "composition_focuses_node"
 ];
 var _POLY_KEY_SET = new Set(UPG_POLYMORPHIC_EDGE_KEYS);
 function isPolymorphicEdge(key) {
@@ -3839,7 +3979,12 @@ var UPG_VALID_CHILDREN = {
     "subscription",
     "forecast",
     // Program Management
+    // `milestone` is a SECOND, shallower parent here (Portfolio Phase 2,
+    // 2026-08-14), alongside its existing `project` parent: a product can own a
+    // milestone outright with no program/project above it. Required by the
+    // hierarchy-orphan guard now that `product_targets_milestone` exists.
     "program",
+    "milestone",
     // Marketing
     "marketing_strategy",
     "press_release",
@@ -4366,7 +4511,15 @@ var UPG_CONTAINMENT_FREE_TYPES = /* @__PURE__ */ new Set([
   // containment. Modelling it as a product child would force a containment edge
   // and read against the whole point of the exercise model (relational, not
   // hierarchical). Same posture as `person`. See ADR 2026-06-02-framework-exercises.
-  "framework_exercise"
+  "framework_exercise",
+  // A composition has no structural parent for the same reason a
+  // framework_exercise does not: it anchors to what it SHOWS, relationally, via
+  // `composition_focuses_node`. Modelling it as a product child would force a
+  // containment edge that reads against the point — a published view is not a
+  // part of the product, it is a lens onto one. This is also what keeps the
+  // type to two edges rather than three: no provenance edge is minted (that is
+  // `workspace_produced_node`, reused) and no parent edge is needed.
+  "composition"
 ]);
 function isContainmentFreeType(entityType) {
   return UPG_CONTAINMENT_FREE_TYPES.has(entityType);
@@ -6742,6 +6895,34 @@ var FRAMEWORK_EXERCISE_LIFECYCLE = {
     }
   ]
 };
+var COMPOSITION_LIFECYCLE = {
+  entity_type: "composition",
+  initial_phase: "draft",
+  terminal_phases: ["archived"],
+  phases: [
+    {
+      id: "draft",
+      status_category: "started",
+      label: "Draft",
+      description: "Being arranged. It has a slug reserved and members placed, but has never been published, so nothing resolves at its address yet.",
+      transitions_to: ["published", "archived"]
+    },
+    {
+      id: "published",
+      status_category: "completed",
+      label: "Published",
+      description: "Live at its slug and linkable. Republishing the same slug stays in this phase and bumps the revision rather than moving the composition.",
+      transitions_to: ["archived", "draft"]
+    },
+    {
+      id: "archived",
+      status_category: "completed",
+      label: "Archived",
+      description: "Withdrawn from the published set but retained, so an existing link resolves to a view marked out of date rather than to nothing. Can be republished.",
+      transitions_to: ["published", "draft"]
+    }
+  ]
+};
 var SPECIFICATION_LIFECYCLE = {
   entity_type: "specification",
   initial_phase: "draft",
@@ -6873,6 +7054,7 @@ var UPG_LIFECYCLES = [
   GROWTH_CAMPAIGN_LIFECYCLE,
   // Workspace
   FRAMEWORK_EXERCISE_LIFECYCLE,
+  COMPOSITION_LIFECYCLE,
   // ── Template-generated lifecycles ─────────────────────────────────
   ...TEMPLATE_LIFECYCLES
 ];
@@ -7764,8 +7946,7 @@ var UPG_MIGRATIONS = {
     {
       from: "metric_definition",
       to: "metric",
-      defaults: { has_implementation: false },
-      reason: "A metric definition is a metric without implementation. Lifecycle property, not a separate type."
+      reason: "A metric definition is a metric without implementation. Lifecycle state, not a separate type. (Corrected in v0.26.0: the default previously stamped `has_implementation: false`, a property `metric` has never declared. Dropped rather than declared, because a metric with no live reading simply has no `current_value`, and a boolean restating that would immediately drift from it.)"
     },
     // ── Experiment consolidation ────────────────────────────────────────────
     {
@@ -7790,8 +7971,8 @@ var UPG_MIGRATIONS = {
     {
       from: "risk_item",
       to: "risk",
-      defaults: { risk_domain: "program" },
-      reason: "risk_item (Program Mgmt) is identical to risk (Legal). Consolidated with risk_domain property."
+      defaults: { risk_type: "program" },
+      reason: "risk_item (Program Mgmt) is identical to risk (Legal). Consolidated onto the single kind axis, `risk_type`. (Corrected in v0.26.0: the default previously named `risk_domain`, a property `risk` has never declared; `program` was added to the `risk_type` enum rather than giving risk a second, drift-prone classification vocabulary.)"
     },
     {
       from: "security_incident",
@@ -7802,8 +7983,8 @@ var UPG_MIGRATIONS = {
     {
       from: "defect_report",
       to: "support_ticket",
-      defaults: { ticket_designation: "defect" },
-      reason: "Defect report is a support ticket with ticket_designation=defect. Same signal interface."
+      defaults: { ticket_type: "bug" },
+      reason: "Defect report is a support ticket with ticket_type=bug. Same signal interface. (Corrected: the default previously named `ticket_designation`, a property `support_ticket` has never declared, so every migrated node was stamped with an undeclared field.)"
     },
     {
       from: "onboarding_flow",
@@ -10825,7 +11006,7 @@ var UPG_PROPERTY_SCHEMA = {
   acceptance_criterion: {
     condition: { type: "string", description: "Required condition (Given/When/Then or plain text)" },
     test_type: { type: "string", enum: ["manual", "automated"], description: "Test mode" },
-    pass_status: { type: "string", enum: ["untested", "pass", "fail"], description: "Current pass/fail" }
+    pass_status: { type: "string", enum: ["untested", "pass", "fail", "regressed", "blocked"], description: "Current verification state of this criterion. `untested` means never attempted; `blocked` means attempted but not verifiable for an environmental reason; `regressed` means previously passing, now failing.", notes: '`blocked` is a distinct state from `untested` (a missing credential or an unreachable dependency is not the same as nobody having tried), which the earlier three-value enum conflated into a silent gap. `regressed` is a criterion-level state and is NOT derivable here, because `acceptance_criterion` stores current state only and keeps no result history. The history lives on the `test_case` to `test_result` series, where a single execution\'s outcome is `TestResultProperties.result_status` and can never itself be "regressed".' }
   },
   // AccessPolicyProperties: Access policy.
   access_policy: {
@@ -11272,14 +11453,14 @@ var UPG_PROPERTY_SCHEMA = {
   // ClassificationAxisProperties: ClassificationAxis: a dimension along which subjects are classified.
   classification_axis: {
     axis_kind: { type: "string", enum: ["categorical", "ordinal", "continuous"], description: "Structural kind of values on this axis. `categorical` = discrete, unordered (most common; CMS architectures). `ordinal` = discrete, ordered (maturity tiers, T-shirt sizes). `continuous` = numeric range (latency budget, price points)." },
-    cardinality: { type: "string", enum: ["single", "multi"], description: 'How many values a subject may hold on this axis at once (UPG 0.11.3). `single` (default) = a subject sits at exactly one value; a re-classification to a new value SUPERSEDES the prior one (the classify writer retires the old same-axis edge and records the move in the reclassification history). `multi` = a subject may legitimately hold several values at once (e.g. an axis like "supported frameworks"); re-classifying ADDS a value and does not supersede. A separate axis from `axis_kind`: an axis can be `categorical` (unordered) yet `single`-select, or `categorical` yet `multi`-select.' }
+    cardinality: { type: "string", enum: ["single", "multi"], description: "How many values a subject may hold on this axis at once. `single` (the default) means re-classifying SUPERSEDES the prior value; `multi` means it ADDS one.", notes: 'Under `single` the classify writer retires the old same-axis edge and records the move in the reclassification history, so the change is traceable rather than silent. `multi` suits an axis like "supported frameworks", where holding several values at once is the truth. A separate axis from `axis_kind`: an axis can be `categorical` (unordered) yet single-select, or `categorical` yet multi-select. The two answer different questions and neither implies the other.' }
   },
   // ClassificationValueProperties: ClassificationValue: a value on a classification axis.
   classification_value: {
     rationale: { type: "string", description: "Short paragraph: why this value earns its own row/column. Longer narrative belongs in `summary_md` or attached `content_piece` nodes." },
     exemplars: { type: "string[]", description: "Free-text examples of products occupying this value. For queryable occupancy, prefer `competitor` nodes with `classified_as` edges. @example ['Nimbus', 'Larch', 'Prism']" },
-    commitments: { type: "object[]", description: "The N (typically 2\u20134) load-bearing commitments that define this category. Each commitment is a structural axis; removing it changes the category. Pairs with `capabilities`: commitments are the *load-bearing definition*; capabilities are the *surface offering*. @example [ { name: 'Typed content graph', description: 'Schemas in code; references as edges; content is structured data.' }, { name: 'Real-time backend', description: 'Live queries, CRDT collaboration, sub-second propagation.' }, { name: 'Embeddable studio', description: 'Editor is a library hosted inside the team app, not an external portal.' }, ]" },
-    capabilities: { type: "object[]", description: "Structured capability bullets across the six canonical surfaces. Each surface appears at most once per `classification_value`. Pairs with `commitments`: capabilities describe what the category *offers*; commitments describe what *defines* it. @example [ { surface: 'delivery', bullets: ['NQL', 'GraphQL', 'REST', 'Live Sync API', 'Asset CDN'] }, { surface: 'extensibility', bullets: ['Custom input components', 'editor plugins'] }, ]" }
+    commitments: { type: "object[]", description: "The load-bearing commitments that define this category, typically two to four. Each is a structural axis: removing it changes the category.", notes: "Pairs with `capabilities`, and the distinction matters when deciding where a bullet belongs: commitments are the load-bearing DEFINITION, capabilities are the surface OFFERING. A capability can be dropped without the category changing; a commitment cannot. A worked set: [ { name: 'Typed content graph', description: 'Schemas in code; references as edges; content is structured data.' }, { name: 'Real-time backend', description: 'Live queries, CRDT collaboration, sub-second propagation.' }, { name: 'Embeddable studio', description: 'Editor is a library hosted inside the team app, not an external portal.' }, ]" },
+    capabilities: { type: "object[]", description: "Structured capability bullets across the six canonical surfaces. Each surface appears at most once per `classification_value`. @example [ { surface: 'delivery', bullets: ['NQL', 'GraphQL', 'REST', 'Live Sync API', 'Asset CDN'] }, { surface: 'extensibility', bullets: ['Custom input components', 'editor plugins'] }, ]", notes: "Pairs with `commitments`, and the distinction decides where a bullet belongs: capabilities describe what the category OFFERS, commitments describe what DEFINES it. Dropping a capability leaves the category intact; dropping a commitment does not." }
   },
   // CodeRepositoryProperties: Code repository.
   code_repository: {
@@ -11314,7 +11495,7 @@ var UPG_PROPERTY_SCHEMA = {
     analysis_type: { type: "string", enum: ["feature_comparison", "positioning", "swot", "pricing"], description: "Type of analysis. `feature_comparison` = side-by-side matrix. `positioning` = competitor positioning relative to each other. `swot` = strengths, weaknesses, opportunities, threats. `pricing` = pricing structure comparison." },
     analysis_date: { type: "string", description: 'ISO date conducted. Competitive intelligence decays quickly; track snapshot age. @example "2026-03-15"' },
     framework_id: { type: "string", description: 'Framework ID (references `UPGFramework.id`). @example "porter-five-forces", "swot-analysis", "competitive-matrix"' },
-    empty_cells: { type: "object[]", description: "Empty cells in a 2-axis classification matrix that earn explicit commentary. Only the strategically interesting cells. Opportunity-kind cells are the most valuable; they identify unoccupied strategic space. Each entry references two `classification_value` nodes by id (one from each `classification_axis` child of this `competitive_analysis`). `validate_graph` enforces that the refs resolve to `classification_value` nodes whose parents are distinct `classification_axis` instances. See `ClassificationValueProperties.commitments` for the inverse \"occupied cell\" structural-definition shape. @example [ { axis_a_value_ref: 'val-git-based', axis_b_value_ref: 'val-structured-text', rationale_kind: 'opportunity', rationale_md: 'No technical reason; only adoption inertia. Watching brief.' }, { axis_a_value_ref: 'val-composable', axis_b_value_ref: 'val-wysiwyg', rationale_kind: 'structural', rationale_md: 'Composable rejects HTML blobs; WYSIWYG requires them.' }, ]" },
+    empty_cells: { type: "object[]", description: "Empty cells in a two-axis classification matrix that earn explicit commentary, and only the strategically interesting ones. Opportunity-kind cells are the most valuable: they identify unoccupied strategic space.", notes: "Each entry references two `classification_value` nodes by id, one from each `classification_axis` child of this `competitive_analysis`. `validate_graph` enforces that the refs resolve to `classification_value` nodes whose parents are distinct `classification_axis` instances, so a cell cannot name two values from the same axis. See `ClassificationValueProperties.commitments` for the inverse \"occupied cell\" structural-definition shape. A worked pair, one of each rationale kind: [ { axis_a_value_ref: 'val-git-based', axis_b_value_ref: 'val-structured-text', rationale_kind: 'opportunity', rationale_md: 'No technical reason; only adoption inertia. Watching brief.' }, { axis_a_value_ref: 'val-composable', axis_b_value_ref: 'val-wysiwyg', rationale_kind: 'structural', rationale_md: 'Composable rejects HTML blobs; WYSIWYG requires them.' }, ]" },
     last_updated: { type: "string", description: 'Provenance: ISO date-time this record was last observed or refreshed. Distinct from `analysis_date` (when the analysis was conducted). @example "2026-06-13"' },
     source: { type: "string", description: 'Provenance: where this was observed. A changelog, pricing, or docs URL, an analyst report, or a research note. @example "https://docs.larch.example/changelog/"' },
     confidence: {
@@ -11384,7 +11565,7 @@ var UPG_PROPERTY_SCHEMA = {
   // CompetitorSignalProperties: Competitor signal: a dated competitor move mapped onto our portfolio.
   competitor_signal: {
     observed_at: { type: "string", description: 'ISO date-time the move was observed. @example "2026-06-10"' },
-    signal_type: { type: "string", enum: ["feature_launch", "pricing_change", "acquisition", "partnership", "market_entry", "reclassification"], description: "Kind of move. `feature_launch` = shipped a feature. `pricing_change` = a plan or tier change. `acquisition` / `partnership` / `market_entry` = strategic moves. `reclassification` = the competitor moved between classification cells on an axis (e.g. ai_integrated to ai_agentic); auto-emitted at the classify-write chokepoint and carries `axis` / `from_value` / `to_value` / `competitor`." },
+    signal_type: { type: "string", enum: ["feature_launch", "pricing_change", "acquisition", "partnership", "market_entry", "reclassification"], description: "Kind of move: a shipped `feature_launch`, a `pricing_change`, the strategic `acquisition` / `partnership` / `market_entry`, or a `reclassification` when the competitor moves between classification cells on an axis.", notes: "`reclassification` is auto-emitted at the classify-write chokepoint rather than authored, and carries `axis`, `from_value`, `to_value` and `competitor` so the move is reconstructable without diffing two snapshots." },
     summary: { type: "string", description: "One-line factual summary of the move (what shipped, not marketing copy)." },
     impact: { type: "string", enum: ["high", "medium", "low"], description: "Expected impact on our position." },
     competitor: { type: "string", description: "Reclassification only. The qualified id of the competitor that moved, as the classify cross-edge source (e.g. `p_rival/n_acme`). Identifies both the subject and its owning product, so `diff_classification({ product })` can filter the history stream." },
@@ -11416,12 +11597,20 @@ var UPG_PROPERTY_SCHEMA = {
   // ComplianceRequirementProperties: Compliance requirement.
   compliance_requirement: {
     regulation: { type: "string", enum: ["gdpr", "ccpa", "hipaa", "soc2", "iso27001", "pci_dss", "other"], description: "Regulation or standard this requirement derives from" },
-    compliance_status: { type: "string", enum: ["compliant", "non_compliant", "in_progress", "not_applicable"], description: "Current compliance posture" }
+    compliance_status: { type: "string", enum: ["compliant", "non_compliant", "in_progress", "not_applicable"], description: "Current compliance posture" },
+    owner: { type: "string", description: "Accountable person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable." }
+  },
+  // CompositionProperties
+  composition: {
+    members: { type: "object[]", description: "The frozen member arrangement, captured at publish. Layout and pointers only, never resolved content." },
+    rev: { type: "number", description: "Monotonic revision, bumped on each republish of the same slug.", notes: "A published revision is a fact about the composition, user-visible as a new print from the same plate, so it is serialised. Worth distinguishing from a store's concurrency token, which shares the name in some backends but is a fact about the table rather than about the thing, and is not spec data." },
+    published_at: { type: "string", description: "ISO timestamp of the most recent publish or republish." },
+    published_by: { type: "string", description: "Publisher handle or email. Display scalar, same posture as `WorkspaceProperties.owner`." }
   },
   // ConfigurationAxisProperties: A named dimension along which the product's composition differs.
   configuration_axis: {
-    values: { type: "string[]", description: "The closed set of values this axis can take. Required: an axis with no values selects nothing and cannot be projected along. Two values is the common case and three is not unusual (a plan ladder). Order is not significant; the axis is categorical, not ordinal. Where the ordering does matter (an entitlement ladder in which each tier includes the one below), that is a classification question, and `classification_axis` with `axis_kind: 'ordinal'` is the instrument for it." },
-    default_value: { type: "string", description: "The value this axis is understood to sit at when nobody says otherwise. Must be a member of `values`. NOTHING APPLIES IT AUTOMATICALLY. Omitting `configuration` on a read returns the UNION, not this projection, because the union is the honest answer to an unqualified question: it is every configuration at once, and silently substituting one of them would hide the others from a reader who did not know to ask. What the field does carry is the declaration convention for `surface_alternates_with_surface` (declare the edge from the surface present under the default) and a documented anchor for tools that later want to offer a starting configuration. It is a claim about the model, not about deployment: it says which value most of the graph was written against, not which configuration most customers are on." },
+    values: { type: "string[]", description: "The closed set of values this axis can take. Required: an axis with no values selects nothing and cannot be projected along. Every `present_under` and `active_when.values` entry must name one of them.", notes: "Two values is the common case and three is not unusual (a plan ladder). Order is not significant: the axis is categorical, not ordinal. Where the ordering does matter (an entitlement ladder in which each tier includes the one below), that is a classification question, and `classification_axis` with `axis_kind: 'ordinal'` is the instrument for it." },
+    default_value: { type: "string", description: "The value this axis is understood to sit at when nobody says otherwise. Must be a member of `values`. NOTHING APPLIES IT AUTOMATICALLY: an unqualified read returns the union, not this projection.", notes: "The union is the honest answer to an unqualified question, because it is every configuration at once; silently substituting one of them would hide the others from a reader who did not know to ask. What the field does carry is the declaration convention for `surface_alternates_with_surface` (declare the edge from the surface present under the default) and a documented anchor for tools that later want to offer a starting configuration. It is a claim about the model, not about deployment: it says which value most of the graph was written against, not which configuration most customers are on." },
     kind: { type: "string", enum: ["feature_flag", "plan_tier", "permission_level", "beta_program", "other"], description: "What kind of lever this is. Names the mechanism family." }
   },
   // ConstraintProperties: Constraint: a named limitation or boundary on product creation.
@@ -11437,7 +11626,7 @@ var UPG_PROPERTY_SCHEMA = {
   contact: {
     contact_role: { type: "string", description: "Job title or role within the account" },
     is_decision_maker: { type: "boolean", description: "Whether this person has purchasing authority" },
-    buying_role: { type: "string", enum: ["champion", "economic_buyer", "technical_evaluator", "end_user", "detractor", "influencer", "procurement", "legal", "security"], description: "Role this contact plays in the buying committee (the decision-making unit). The substrate of enterprise multi-threading and of qualification frameworks (MEDDICC/SPICED): a deal with no `champion` and no `economic_buyer` mapped is single-threaded and at risk. `is_decision_maker` becomes largely derivable (`buying_role = economic_buyer`) but is kept for back-compat. @example 'economic_buyer'" }
+    buying_role: { type: "string", enum: ["champion", "economic_buyer", "technical_evaluator", "end_user", "detractor", "influencer", "procurement", "legal", "security"], description: "Role this contact plays in the buying committee, the decision-making unit. @example 'economic_buyer'", notes: "The substrate of enterprise multi-threading and of qualification frameworks such as MEDDICC and SPICED: a deal with no `champion` and no `economic_buyer` mapped is single-threaded and at risk, which is a fact the graph can answer rather than a judgement someone has to make. `is_decision_maker` becomes largely derivable from this (`buying_role = economic_buyer`) but is kept for back-compat." }
   },
   // ContentCalendarProperties: Content calendar.
   content_calendar: {
@@ -11558,7 +11747,8 @@ var UPG_PROPERTY_SCHEMA = {
   data_contract: {
     retention_period: { type: "string", description: "How long data is retained before deletion" },
     deletion_policy: { type: "string", description: "Policy governing data deletion" },
-    third_party_sharing: { type: "boolean", description: "Whether data is shared with third parties" }
+    third_party_sharing: { type: "boolean", description: "Whether data is shared with third parties" },
+    owner: { type: "string", description: "Owning person or team accountable for the contract. Promote to a `node_owned_by_team` edge if ownership must be queryable." }
   },
   // DataDomainProperties: DataDomain. A coarse-grained grouping of related data assets (sources,
   data_domain: {
@@ -11604,7 +11794,8 @@ var UPG_PROPERTY_SCHEMA = {
   // DataProductProperties: DataProduct entity.
   data_product: {
     data_product_type: { type: "string", enum: ["report", "dataset", "stream", "api", "ml_feature", "other"], description: "Classification of the data product (UPG-579 Option B)." },
-    sla_freshness: { type: "string", description: 'Freshness SLA commitment (e.g. "< 1 hour")' }
+    sla_freshness: { type: "string", description: 'Freshness SLA commitment (e.g. "< 1 hour")' },
+    owner: { type: "string", description: "Owning person or team. Sibling of `data_domain.steward`: use `owner` for the accountable party of a single data product, `steward` for a whole domain. Promote to a `node_owned_by_team` edge if ownership must be queryable." }
   },
   // DataQualityRuleProperties: DataQualityRule entity.
   data_quality_rule: {
@@ -11634,7 +11825,7 @@ var UPG_PROPERTY_SCHEMA = {
     deal_value: { type: "number", description: "Monetary value of the deal" },
     close_date: { type: "string", description: "Expected close date (ISO format)" },
     probability: { type: "number", description: "Likelihood of closing (0-100%)" },
-    deal_outcome: { type: "string", enum: ["won", "lost", "no_decision"], description: "Terminal result of the deal. An Event-axis outcome (the verdict on a one-time event), NOT a lifecycle phase, so it is `deal_outcome` and not `deal_status` per the status-convention Rule 3. Lifecycle (open/won/lost as phases) belongs on the base `status` slot; this records the win/loss verdict a closed deal carries and gives `deal_lost_to_competitor` / win-loss study derivations their anchor. @example 'won'" },
+    deal_outcome: { type: "string", enum: ["won", "lost", "no_decision"], description: "Terminal result of the deal: the win or loss verdict a closed deal carries. @example 'won'", notes: "An Event-axis outcome (the verdict on a one-time event) and NOT a lifecycle phase, so it is `deal_outcome` rather than `deal_status`, per status-convention Rule 3. Lifecycle (open, won and lost as phases) belongs on the base `status` slot. This field is what gives `deal_lost_to_competitor` and win-loss study derivations their anchor." },
     deal_type: { type: "string", enum: ["new_business", "expansion", "renewal"], description: "Motion this deal belongs to. Mirrors `PipelineSales.pipeline_type` at the deal grain; `renewal` is the value `subscription_renews_via_deal` points at. @example 'expansion'" },
     next_step: { type: "string", description: "The single most-used CRM field: the next concrete action to move the deal. Free text on purpose (a coordination note, not a structured task). @example 'Send security questionnaire to procurement'" },
     next_step_date: { type: "string", description: "When the `next_step` is due (ISO format)." },
@@ -11650,7 +11841,8 @@ var UPG_PROPERTY_SCHEMA = {
         normalized: { type: "number", description: "Normalized 0-1 value for cross-tool comparison (optional)." }
       },
       required: ["value", "label"]
-    }
+    },
+    owner: { type: "string", description: "Accountable person or team carrying the deal. Promote to a `node_owned_by_person` edge if ownership must be queryable." }
   },
   // DecisionProperties: Decision record. Strategic, product, engineering, or design.
   decision: {
@@ -11863,7 +12055,8 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // EpicProperties: A collection of related user stories that delivers a feature or capability.
   epic: {
-    estimate: { type: "string", description: 'Rough size estimate (e.g. "3 sprints", "L", "13 points")' },
+    effort: { type: "string", description: 'Effort estimate (e.g. "2h", "1d", "3 points"). Use a consistent unit within your team. Canonical name for the work-item size family (`epic`, `user_story`, `task`).' },
+    estimate: { type: "string", description: 'Rough size estimate (e.g. "3 sprints", "L", "13 points"). @deprecated STAGED, release number assigned at release prep (docket Track "Docket wave 2"). Use `effort`, the family-uniform name already carried by `user_story` and `task`. `estimate` was epic\'s lone divergent spelling of the same concept and it caused real misreads (the app read `estimate` on `user_story`, where only `effort` is declared). Kept (not removed) for back-compat; removal is a later major. Writers: emit `effort`. Readers: prefer `effort`, fall back to `estimate`.' },
     priority: { type: "string", enum: ["urgent", "high", "medium", "low", "none"], description: "Task-level priority" },
     owner: { type: "string", description: "Responsible person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable." },
     start_date: { type: "string", description: "ISO date work begins" },
@@ -11880,7 +12073,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // EvalBenchmarkProperties: Evaluation benchmark.
   eval_benchmark: {
-    benchmark_type: { type: "string", enum: ["accuracy", "latency", "cost", "safety", "custom"], description: "Measured dimension" },
+    benchmark_type: { type: "string", enum: ["accuracy", "latency", "cost", "safety", "precision_recall", "task_success", "coherence", "custom"], description: "Measured dimension.", notes: 'Widened in 0.31.0 with the three dimensions an eval suite actually reports and this set could not express: `precision_recall` (two numbers, not one accuracy figure, and the pair is the point, because a detector that fires on everything scores perfectly on recall alone), `task_success` (did the agent achieve the goal), and `coherence` (rubric-graded, for multi-step runs). THIS ENUM IS A DIMENSION AXIS, AND IT SHOULD STAY ONE. An eval suite\'s families are a SUBJECT axis (what is under test), and a dimension cannot separate subjects, which is why several families legitimately share `task_success`. The subject is expressed on the EDGE, not here: `eval_benchmark_measures_node` names what a benchmark measures by pointing at it. So "which benchmarks cover the importer" is a traversal, and this property stays a clean answer to a different question, "what dimension does this benchmark report". The commissioning brief hoped the enum would carry both; splitting them across the enum and the edge is the better answer, and it needs no third mechanism. Corollary worth stating, since it is load-bearing: do NOT add subject-shaped values here. `tool_use` or `documentation` would encode on this axis what the edge already carries, and the two would drift the first time a benchmark measured something its enum value did not admit.' },
     test_case_count: { type: "number", description: "Test cases in the suite", modifier: "derived" },
     passing_threshold: { type: "number", description: "Minimum passing score" },
     last_run: { type: "string", description: "ISO date of the most recent run" }
@@ -11896,7 +12089,8 @@ var UPG_PROPERTY_SCHEMA = {
     output_token_count: { type: "number", description: "Output tokens" },
     cost: { type: "number", description: "Total run cost" },
     error_rate: { type: "number", description: "Percentage of test cases that errored" },
-    feedback_scores: { type: "string", description: "Feedback score summary (human or automated)" }
+    feedback_scores: { type: "string", description: "Feedback score summary (human or automated)" },
+    metric_scores: { type: "object[]", description: "Per-metric scores, one entry per measured metric.", notes: "Added in 0.31.0 because `score` is a single aggregate and the forcing case needs two numbers: precision and recall, reported separately. An aggregate hides the only interesting failure mode, which is a detector that catches everything by firing on everything. `sample_size` is not optional decoration, and as of 0.31.0 the type says so: it is a REQUIRED member of `MetricScore`. A sampled run reports its sample size beside its score, always, so a comparison across runs can never quietly compare different sample sizes. A number without its denominator is not a smaller measurement, it is not a measurement, and a remark saying `always` over a field typed optional is a contract only the careful reader honours. The entry shape is the exported `MetricScore` interface rather than an anonymous literal, so a consumer can name the thing it is building. This is one of two `object[]` properties in the spec; the other, `composition.members`, already exports `CompositionMember`. The rejected alternative was two runs per benchmark, which needs no spec change and makes every question about a benchmark's quality a join, encoding a measurement artifact as graph structure." }
   },
   // EventProperties: Event.
   event: {
@@ -12000,6 +12194,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // ExperimentRunProperties: Execution evidence for a structured test of a hypothesis (UCS pattern P6: event-occurrence).
   experiment_run: {
+    experiment_type: { type: "string", enum: ["ab_test", "growth", "pricing"], description: "What sort of experiment this run is: `ab_test` is a controlled split between variants, `growth` an acquisition or activation experiment, `pricing` a packaging or willingness-to-pay one. Distinct from `disposition`, which is the outcome axis.", notes: "Three retired types (`ab_test`, `growth_experiment`, `pricing_experiment`) collapsed into `experiment_run` precisely along this axis, and the migration defaults stamp it so the distinction survives consolidation. Extensible: further kinds may be added in a minor release." },
     actual_start_date: { type: "string", description: "ISO actual start date (may differ from the plan's `planned_start_date`)" },
     actual_end_date: { type: "string", description: "ISO actual end date" },
     actual_reach: { type: "number", description: "Observed reach: how many people the run actually touched" },
@@ -12167,7 +12362,8 @@ var UPG_PROPERTY_SCHEMA = {
   // FrameworkExerciseProperties: Framework exercise: one run of a framework over a set of entities.
   framework_exercise: {
     framework_id: { type: "string", description: "Which framework this exercise runs: a framework id (e.g. 'moscow', 'rice-scoring', 'kano-model'). Resolves against the framework catalog." },
-    inputs_snapshot: { type: "object", description: "Optional frozen copy of the framework's input spec at apply time, so a historical exercise still renders correctly if the framework definition later evolves (inputs added, removed, or rescaled)." }
+    inputs_snapshot: { type: "object", description: "Optional frozen copy of the framework's input spec at apply time, so a historical exercise still renders correctly if the framework definition later evolves (inputs added, removed, or rescaled)." },
+    input_weights: { type: "object", description: "Relative multiplier per framework input for this run, keyed by input id. @example const properties: FrameworkExerciseProperties = { framework_id: 'rice-scoring', input_weights: { reach: 1, impact: 2, confidence: 1, effort: 1.5 }, }", notes: "A weight belongs to the RUN, not to any entity it scores: one weight per input, shared by every scored entity, which is why it sits here and not on the `framework_exercise_includes_node` edge alongside the per-entity result. Named `input_weights` rather than a bare `weight` deliberately, and the collision is live rather than hypothetical: `getPropertyDefaultScale` keys on property NAME alone and ignores entity type, and `PROPERTY_SCALE_MAP` already maps `weight` to the `importance_5` ordinal. A bare `weight` here would silently resolve to a 1-5 assessment scale, which is the wrong type, range and meaning for a multiplier. The plural also matches the spec's own vocabulary: a framework declares *inputs*, not dimensions." }
   },
   // FunnelProperties: Funnel entity.
   funnel: {
@@ -12184,7 +12380,8 @@ var UPG_PROPERTY_SCHEMA = {
   // GlossaryTermProperties: GlossaryTerm entity.
   glossary_term: {
     term_definition: { type: "string", description: "Plain-language definition of the term" },
-    synonyms: { type: "string[]", description: "Alternative names or abbreviations for this term" }
+    synonyms: { type: "string[]", description: "Alternative names or abbreviations for this term" },
+    owner: { type: "string", description: "Person or team accountable for keeping the definition current. Promote to a `node_owned_by_person` edge if ownership must be queryable." }
   },
   // GrowthCampaignProperties: GrowthCampaign entity.
   growth_campaign: {
@@ -12257,7 +12454,7 @@ var UPG_PROPERTY_SCHEMA = {
   // HypothesisEvidenceProperties
   hypothesis_evidence: {
     evidence_type: { type: "string", enum: ["experiment_run", "observation", "quote", "metric_change", "market_data", "interview"], description: "Kind of evidence. Drives renderer + filter UI. The provenance edge (`derived_from_*`) carries the actual source node reference per P14; this enum is typing/UI metadata." },
-    direction: { type: "string", enum: ["supports", "refutes", "neutral"], description: "Direction relative to the parent claim. Canonical direction axis aligned to `Evidence.direction` so every direction-of-evidence property uses the same vocab. `supports` = paired with the `supports` edge. `refutes` = paired with the `refutes` edge. `neutral` = data insufficient or noisy. BREAKING in v0.4.0: legacy `'confirms'`, `'disconfirms'`, `'inconclusive'` no longer type-check. Migration: `confirms \u2192 supports`, `disconfirms \u2192 refutes`, `inconclusive \u2192 neutral`." },
+    direction: { type: "string", enum: ["supports", "refutes", "neutral"], description: "Direction relative to the parent claim: `supports` and `refutes` pair with the edges of the same name, `neutral` means the data is insufficient or noisy. BREAKING in v0.4.0: `confirms`, `disconfirms` and `inconclusive` no longer type-check. Migration is one-to-one: confirms to supports, disconfirms to refutes, inconclusive to neutral.", notes: "Aligned to `Evidence.direction` so every direction-of-evidence property in the spec shares one vocabulary." },
     weight: {
       type: "assessment",
       scale_id: "importance_5",
@@ -12327,6 +12524,7 @@ var UPG_PROPERTY_SCHEMA = {
     novelty: { type: "string", enum: ["known", "surprising", "contradictory"], description: "Novelty against existing knowledge. `known` = confirms what we already believed. `surprising` = challenges or extends our understanding. `contradictory` = directly conflicts with a prior assumption." },
     actionability: { type: "string", enum: ["immediate", "needs_validation", "informational"], description: "Current actionability. `immediate` = clear action, no further research needed. `needs_validation` = promising but requires more evidence. `informational` = important context, no direct action." },
     source_method: { type: "string", description: 'Producing research method. @example "usability_study", "interview_series", "survey"' },
+    source_domain: { type: "string", description: 'Which discipline the insight came out of. The second provenance axis, symmetrical with `source_method`: that one is HOW the insight was produced, this one is WHICH PRACTICE produced it, and neither substitutes for the other. @example "ux", "support", "sales", "data_science"', notes: "Declared in v0.26.0 so the retired `ux_insight` type's migration default (`source_domain: 'ux'`) lands in a typed field rather than being lost." },
     statement: { type: "string", description: 'Insight statement in plain language. Write as an active, present-tense assertion. @example "Users consistently skip the tutorial because they trust their ability to explore independently."' },
     implications: { type: "string", description: "Product implications. The so-what." }
   },
@@ -12348,8 +12546,8 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // InternalDocProperties: Internal document.
   internal_doc: {
-    doc_type: { type: "string", enum: ["rfc", "runbook", "guide", "spec", "onboarding", "other"], description: "Classification of the document" },
-    url: { type: "string", description: "URL or path to the document" }
+    doc_type: { type: "string", enum: ["rfc", "runbook", "guide", "spec", "onboarding", "other"], description: "Classification of the document. @deprecated use `document.document_type`" },
+    url: { type: "string", description: "URL or path to the document. @deprecated use `document.source_url`" }
   },
   // InterviewGuideProperties: Interview guide document.
   interview_guide: {
@@ -12707,7 +12905,7 @@ var UPG_PROPERTY_SCHEMA = {
     range_max: { type: "number", description: "Maximum expected or ceiling value" },
     cadence: { type: "string", enum: ["continuous", "hourly", "daily", "weekly", "monthly", "quarterly", "yearly", "on_demand", "other"], description: "Measurement cadence. Canonical `Cadence` since v0.4.0. `'realtime'` migrates to `'continuous'`; all other values 1:1." },
     owner: { type: "string", description: "Person or team responsible for tracking this metric. Promote to a `node_owned_by_person` edge if ownership must be queryable." },
-    metric_health: { type: "string", enum: ["healthy", "at_risk", "unhealthy", "unknown"], description: "Universal health rollup. Orthogonal to lifecycle and `guardrail_status`. Applies to every metric regardless of `designation`. `healthy` = trending well against target / inside safe range. `at_risk` = drifting, approaching breach or target shortfall. `unhealthy` = missed target or breached; action needed. `unknown` = no current reading or not yet measured. For guardrails specifically, `guardrail_status` remains the breach-specific signal (`safe`/`warning`/`breached`)." },
+    metric_health: { type: "string", enum: ["healthy", "at_risk", "unhealthy", "unknown"], description: "Universal health rollup, applying to every metric regardless of `designation`: `healthy` is inside range, `at_risk` is drifting toward a breach or shortfall, `unhealthy` has missed or breached, `unknown` has no current reading.", notes: "Orthogonal to lifecycle and to `guardrail_status`. For guardrails specifically, `guardrail_status` remains the breach-specific signal (`safe` / `warning` / `breached`), so a guardrail carries both: one says how it is trending, the other says whether it has been crossed." },
     guardrail_threshold_min: { type: "number", description: "Lower bound for guardrail safety (below this = breach)" },
     guardrail_threshold_max: { type: "number", description: "Upper bound for guardrail safety (above this = breach)" },
     guardrail_status: { type: "string", enum: ["safe", "warning", "breached"], description: "Current guardrail health state" }
@@ -12727,7 +12925,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // MilestoneProperties: Milestone.
   milestone: {
-    milestone_order: { type: "number", description: "Display order of this milestone within its parent project (0-indexed). The scalar ordering convention shared with `journey_step.step_order` and `journey_action.action_order` (UPG-663 / UPG-674). Orders the delivery milestones a project moves through, independent of `due_date`." },
+    milestone_order: { type: "number", description: "Display order of this milestone within its parent (0-indexed). The scalar ordering convention shared with `journey_step.step_order` and `journey_action.action_order` (UPG-663 / UPG-674). Orders the delivery milestones a parent moves through, independent of `due_date`.", notes: "The parent is whichever of the two milestone parents the graph actually uses: a `project` via `project_targets_milestone`, or a `product` directly via `product_targets_milestone` (Portfolio Phase 2, for milestones a product owns outright with no program or project above them). The order is scoped to that one parent, never global." },
     due_date: { type: "string", description: "Target due date (ISO format)" },
     met_on_time: { type: "boolean", description: "Whether the milestone was met on time" }
   },
@@ -12957,8 +13155,8 @@ var UPG_PROPERTY_SCHEMA = {
     motivation: { type: "string", description: 'Primary motivation or driving need @example "Making confident, evidence-based decisions"' },
     tech_comfort: { type: "string", enum: ["low", "medium", "high", "expert", "other"], description: "Tech comfort. Closed set so personas across products compare on the same axis. Free-text colour belongs in `context` or `motivation`." },
     domain_expertise: { type: "string", description: 'Industry or domain knowledge this persona brings @example "10+ years SaaS experience", "New to healthcare IT"' },
-    audience_role: { type: "string", enum: ["buyer", "user", "champion", "influencer", "partner"], description: 'Role in the buying / adoption decision (the decision-making-unit split): who signs (buyer) vs who uses (user) vs who advocates internally (champion) vs who shapes the choice (influencer) vs who delivers / implements (partner). A portfolio must separate the economic buyer from the practitioner user; they are distinct personas with distinct jobs. Closed set so roles compare across products. @example "buyer"' },
-    actor_kind: { type: "string", enum: ["human", "agent", "system"], description: 'Who performs the work: a human archetype (default), an autonomous AI agent (e.g. Content Agent), or a non-agentic platform service. Absent = `human`, so existing personas need no migration. An `agent` persona is a first-class actor that participates in journeys via the same persona machinery and that humans delegate to via `persona_delegates_to_persona`. Human-coverage / segmentation metrics count `human` only; agent/system are opt-in. @example "agent"' }
+    audience_role: { type: "string", enum: ["buyer", "user", "champion", "influencer", "partner"], description: 'Role in the buying or adoption decision: who signs (`buyer`), who uses (`user`), who advocates internally (`champion`), who shapes the choice (`influencer`), and who delivers it (`partner`). A closed set, so roles compare across products. @example "buyer"', notes: "A portfolio must separate the economic buyer from the practitioner user: they are distinct personas with distinct jobs, and collapsing them is how a product ends up built for whoever was easiest to interview." },
+    actor_kind: { type: "string", enum: ["human", "agent", "system"], description: 'Who performs the work: a human archetype, an autonomous AI agent, or a non-agentic platform service. Absent means `human`, so existing personas need no migration. @example "agent"', notes: "An `agent` persona is a first-class actor: it participates in journeys through the same persona machinery, and humans delegate to it via `persona_delegates_to_persona`. Human-coverage and segmentation metrics count `human` only, so agent and system personas are opt-in rather than silently inflating a coverage number." }
   },
   // PipelineSalesProperties: Sales pipeline.
   pipeline_sales: {
@@ -13044,7 +13242,7 @@ var UPG_PROPERTY_SCHEMA = {
     url: { type: "string", description: "Where the product lives. Marketing site, app store URL, etc.", modifier: "volatile" },
     logo_url: { type: "string", description: "Logo or icon URL. Used to render product cards and lists.", modifier: "volatile" },
     launched_at: { type: "string", description: "When the product became generally available (ISO 8601)" },
-    described_configuration: { type: "string", description: `The product configuration this graph describes, named in plain language. A product's composition often differs by feature flag, plan tier, permission level or beta programme: surfaces appear, disappear, or are replaced by different surfaces with different occupants. A graph that models one of those without saying which is qualified by a condition nobody wrote down, and every fact in it inherits that silence. NAMING, NOT CONFIGURING. This is a label for readers. Nothing reads it to gate, filter, or alter how a tool interprets the graph, and it makes no claim about which configuration most customers are on. @example "Enterprise plan, split-navigation flag on" @example "Default: free tier, all flags off"` }
+    described_configuration: { type: "string", description: 'The product configuration this graph describes, named in plain language. A label for readers: nothing reads it to gate, filter, or alter how a tool interprets the graph. @example "Enterprise plan, split-navigation flag on"', notes: "A product's composition often differs by feature flag, plan tier, permission level or beta programme: surfaces appear, disappear, or are replaced by different surfaces with different occupants. A graph that models one of those without saying which is qualified by a condition nobody wrote down, and every fact in it inherits that silence. It makes no claim about which configuration most customers are on. Where a product genuinely ships several and the differences matter, declare a `configuration_axis` instead and let each fact say which values it holds under." }
   },
   // ProductAreaProperties: ProductArea entity.
   product_area: {
@@ -13096,7 +13294,10 @@ var UPG_PROPERTY_SCHEMA = {
   qa_session: {
     session_type: { type: "string", enum: ["exploratory", "regression", "smoke", "uat"], description: "Type of QA session" },
     duration_minutes: { type: "number", description: "Duration of the session in minutes" },
-    bugs_found: { type: "number", description: "Number of bugs found during the session" }
+    bugs_found: { type: "number", description: "Number of bugs found during the session" },
+    environment: { type: "string", enum: ["local", "ci", "staging", "sandbox", "production_mirror"], description: "Environment the session was run against. Single-valued, unlike `TestPlanProperties.environments` (a plan spans several); the enum is the same one, mirroring `TestEnvironmentProperties.env_type`." },
+    outcome_summary: { type: "string", description: "Plain-English outcome of the session: what it established, not how many bugs it counted (`bugs_found`). Named `outcome_summary`, matching `ExperimentRunProperties.outcome_summary`, because a bare `outcome` would collide with the `outcome` entity type." },
+    executed_at: { type: "string", description: "ISO timestamp of when the session was run. Mirrors `TestResultProperties.executed_at`." }
   },
   // QueueTopicProperties: Message queue or topic.
   queue_topic: {
@@ -13163,7 +13364,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // ReleaseStrategyProperties: Release strategy.
   release_strategy: {
-    strategy_type: { type: "string", enum: ["blue_green", "canary", "rolling", "recreate", "feature_flag"], description: 'How a new version reaches production. `blue_green` = instant switch between two identical environments. `canary` = gradual percentage rollout. `rolling` = replace instances incrementally. `recreate` = take down old, bring up new. `feature_flag` = code ships, features gated. @example "canary" for gradual rollout, "blue_green" for instant switch with instant rollback' },
+    strategy_type: { type: "string", enum: ["blue_green", "canary", "rolling", "recreate", "feature_flag"], description: 'How a new version reaches production. @example "canary" for gradual rollout, "blue_green" for instant switch with instant rollback', notes: "`blue_green` switches instantly between two identical environments. `canary` rolls out by percentage. `rolling` replaces instances incrementally. `recreate` takes the old down before bringing the new up. `feature_flag` ships the code with the features gated." },
     canary_percentage: { type: "number", description: "Traffic routed to canary. Applies when `strategy_type === 'canary'`. @example 5 (5% initial canary before full rollout)" },
     rollback_criteria: { type: "string", description: 'Rollback triggers, automatic or manual. @example "Error rate > 1% over 5 minutes", "Latency p99 > 2x baseline"' },
     bake_time: { type: "string", description: 'Soak time before promoting to full production. @example "30m", "2h", "24h"' },
@@ -13224,7 +13425,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // RiskProperties: Risk.
   risk: {
-    risk_type: { type: "string", enum: ["technical", "business", "legal", "security", "operational"], description: "Domain the risk belongs to" },
+    risk_type: { type: "string", enum: ["technical", "business", "legal", "security", "operational", "program"], description: "Domain the risk belongs to. The single kind axis for `risk`: there is no second classification vocabulary. `program` added in v0.26.0 so the retired `risk_item` (Program Management) type has a home on the canonical `risk` after consolidation, rather than a parallel `risk_domain` field free to drift from this one." },
     probability: {
       type: "assessment",
       scale_id: "confidence_5",
@@ -13372,7 +13573,8 @@ var UPG_PROPERTY_SCHEMA = {
     effective_date: { type: "string", description: "ISO effective date" },
     url: { type: "string", description: "Policy document URL" },
     policy_status: { type: "string", enum: ["draft", "active", "under_review", "retired"], description: "Lifecycle status" },
-    rule_strength: { type: "string", enum: ["must", "must_not", "exception", "warning", "guideline"], description: "Imperative force" }
+    rule_strength: { type: "string", enum: ["must", "must_not", "exception", "warning", "guideline"], description: "Imperative force" },
+    owner: { type: "string", description: "Owning person or team accountable for the policy. Promote to a `node_owned_by_team` edge if ownership must be queryable." }
   },
   // SecurityReviewProperties: Security review.
   security_review: {
@@ -13572,12 +13774,12 @@ var UPG_PROPERTY_SCHEMA = {
     surface_kind: { type: "string", enum: ["shell", "tool", "pane", "region", "slot", "gutter", "action_bar", "overlay", "ambient"], description: "Structural kind. Determines what may legally nest inside this surface." },
     persistence: { type: "string", enum: ["always", "conditional", "on_demand", "transient"], description: "How reliably the surface is present." },
     visibility_condition: { type: "string", description: 'When the surface appears, in plain language. Pairs with `persistence: \'conditional\'`, which states *that* it is conditional; this states *what* the condition is. @example "A node is selected", "Only for workspace admins"' },
-    capacity: { type: "number", description: 'How many occupants ONE INSTANCE of the surface holds at once, as a non-negative count. Count the instances themselves with `cardinality`. CAPACITY IS ALWAYS INTENT, NEVER OBSERVED BEHAVIOUR. It records the cap the design asserts, so a banner region declared `capacity: 1` keeps saying 1 even after someone finds it rendering four. Reality that has drifted from the declared intent is recorded as a trackable, assignable debt item on `surface_deviates_via_technical_debt_item`, not by quietly editing this number up to match the bug. Editing it to match would destroy the only record that a gap exists. ABSENT MEANS UNBOUNDED. UPG has no union-typed property primitive (`PropertyDefinition.type` is a single scalar kind), so the proposed `integer | unbounded` shape is expressed as an optional number whose absence carries the "no cap" reading, rather than a magic sentinel value that every consumer would have to special-case. `0` is a real cap meaning "nothing may occupy this surface" (a reserved place), not "unbounded". THREE STATES, AND THEY ARE ALL DIFFERENT. Absent = unbounded, no cap stated. `0` = a reserved place nothing may occupy. `null` = neither of those, and nothing this field defines; it is what you get by writing an explicit null rather than removing the key, and no consumer reads it as a cap. To return this property to ABSENT, remove the key with `update_node`\'s or `batch_update_nodes`\' `unset_properties`, since a property merge preserves anything you omit. UNBOUNDED IS NOT AN EXEMPTION FROM SCRUTINY. The contention detector reads an absent capacity as a threshold of 1, on the reasoning that a surface which states no limit has stated no answer either, so several occupants is exactly the unrecorded decision worth naming. Declaring a real capacity is therefore the way to quiet the check honestly, and the only way that also records something true.' },
+    capacity: { type: "number", description: "How many occupants ONE INSTANCE of the surface holds at once, as a non-negative count. Absent means unbounded, `0` means a reserved place nothing may occupy. Always the cap the design INTENDS, never what was observed rendering. Count the instances themselves with `cardinality`.", notes: "Intent, not observation: a banner region declared `capacity: 1` keeps saying 1 even after someone finds it rendering four. Reality that has drifted from the declared intent belongs on `surface_deviates_via_technical_debt_item` as a trackable, assignable debt item. Editing this number up to match the bug would destroy the only record that a gap exists. Why absence rather than a sentinel: UPG has no union-typed property primitive, so `integer | unbounded` is expressed as an optional number whose absence carries the \"no cap\" reading, instead of a magic value every consumer would have to special-case. Three states, all different. ABSENT is unbounded, no cap stated. `0` is a reserved place. `null` is neither, and nothing this field defines: it is what an explicit null write leaves behind, and no consumer reads it as a cap. To return the property to absent, remove the key with `update_node`'s or `batch_update_nodes`' `unset_properties`, since a property merge preserves anything omitted. Unbounded is not an exemption from scrutiny. The contention detector reads an absent capacity as a threshold of 1, because a surface that states no limit has stated no answer either, so several occupants is exactly the unrecorded decision worth naming. Declaring a real capacity is the way to quiet the check honestly, and the only way that also records something true." },
     cardinality: { type: "string", enum: ["1", "0..1", "1..n", "0..n"], description: "How many instances of this surface exist. `capacity` counts occupants within one instance; this counts the instances." },
     instance_scope: { type: "string", enum: ["global", "per_parent"], description: 'What an instance is scoped to: one shared instance for the product, or one per containing surface. Decides whether "the product has this surface" is a true sentence or a per-parent one.' },
     composition_mode: { type: "string", enum: ["exclusive", "additive", "chained"], description: "How the occupants relate: one wins (`exclusive`), all coexist (`additive`), or each wraps the next (`chained`). Declaring `chained` exempts the surface from `contended-surface-without-arbitration`; leaving this unset does not." },
-    arbitration_rule: { type: "string", description: 'Who wins when more occupants want the surface than `capacity` allows, and why. ABSENCE IS MEANINGFUL: a null or empty `arbitration_rule` on a contested surface means nobody decided, which is exactly what the `contended-surface-without-arbitration` anti-pattern detects. Do not fill this in with a placeholder to silence the check. @example "Highest priority wins; ties break to the most recently updated."' },
-    arbitration_state: { type: "string", enum: ["enforced_documented", "enforced_undocumented", "safe_by_coincidence", "none"], description: 'Whether the arbitration answer is enforced, written down, both, or neither. Separates "enforced in code but never transcribed" (ten minutes of typing) from "never decided" (a design meeting) from "safe only because nothing has collided yet" (the dangerous one).' },
+    arbitration_rule: { type: "string", description: 'Who wins when more occupants want the surface than `capacity` allows, and why. Absence is meaningful: on a contested surface it means nobody decided. @example "Highest priority wins; ties break to the most recently updated."', notes: "An empty or absent rule on a contested surface is exactly what `contended-surface-without-arbitration` detects. Do not fill it in with a placeholder to silence the check: the check exists to find the unrecorded decision, and a placeholder hides it without settling anything. The field is overloaded across composition modes, which is worth knowing before writing one. On an `exclusive` surface it records DISPLACEMENT (who is not rendered). On an `additive` surface everyone fits, so what it records is ORDER. Only the displacement reading is what the contention detector reads." },
+    arbitration_state: { type: "string", enum: ["enforced_documented", "enforced_undocumented", "safe_by_coincidence", "none", "no_contention_by_design"], description: "Whether the arbitration answer is enforced, written down, both, neither, or not owed at all. Leaving the field unset means unassessed, and always did.", notes: 'The separations are the whole point of the field, because absence alone conflates four situations with four different remediations: "enforced in code but never transcribed" is ten minutes of typing, "never decided" is a design meeting, "safe only because nothing has collided yet" is the dangerous one, and "nothing to decide, the occupants never compete" is a chained surface, which owes no arbitration rule at all.' },
     extensibility: { type: "string", enum: ["closed", "plugin_registerable", "user_configurable"], description: "Who may add occupants to the surface." },
     mutates_content: { type: "boolean", description: "Whether occupying this surface can change the underlying content, as opposed to only selecting or revealing it. The selector-versus-mutator distinction: a gutter that toggles a value is a mutator, a gutter that jumps the cursor is not." },
     dimensional_constraint: { type: "string", description: 'The hard spatial budget the surface imposes on its occupants, in whatever unit the design system speaks. @example "292px wide", "25px per field", "two grid columns"' }
@@ -13745,7 +13947,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // TestSuiteProperties: Test suite.
   test_suite: {
-    suite_type: { type: "string", enum: ["unit", "integration", "e2e", "performance", "security", "accessibility"], description: "Category of test suite" },
+    suite_type: { type: "string", enum: ["unit", "integration", "e2e", "performance", "security", "accessibility", "visual"], description: "Category of test suite. The single canonical verification-method vocabulary in the spec: do not mint a second one at criterion level.", notes: "`visual` covers visual-regression and screenshot-diff suites, whose evidence is a rendered-output comparison rather than an assertion over behaviour. Before it existed, producers mapped visual suites onto `integration` as the least-wrong stock value, which made them indistinguishable from genuine integration coverage." },
     test_count: { type: "number", description: "Number of tests in the suite", modifier: "derived" },
     pass_rate: { type: "number", description: "Percentage of tests passing (0-100)", modifier: "snapshot" },
     last_run: { type: "string", description: "ISO date of last execution" },
@@ -13788,7 +13990,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // ThreatModelProperties: Threat model.
   threat_model: {
-    methodology: { type: "string", enum: ["stride", "dread", "pasta", "attack_tree", "other"], description: 'Methodology. `stride` = Spoofing, Tampering, Repudiation, Information Disclosure, DoS, Elevation of Privilege (OWASP standard). `dread` = Damage, Reproducibility, Exploitability, Affected users, Discoverability (numeric scoring). `pasta` = Process for Attack Simulation and Threat Analysis (7-stage). `attack_tree` = hierarchical tree of attack paths. @example "stride" is the most widely used methodology for web applications' },
+    methodology: { type: "string", enum: ["stride", "dread", "pasta", "attack_tree", "other"], description: 'Threat-modelling methodology: `stride`, `dread`, `pasta`, or `attack_tree`. @example "stride" is the most widely used methodology for web applications', notes: "`stride` is the OWASP standard (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege). `dread` is numeric scoring (Damage, Reproducibility, Exploitability, Affected users, Discoverability). `pasta` is the seven-stage Process for Attack Simulation and Threat Analysis. `attack_tree` is a hierarchical tree of attack paths." },
     scope: { type: "string", description: 'What system, feature, or data flow is being analysed. @example "user authentication", "payment processing", "admin API"' },
     last_reviewed: { type: "string", description: 'ISO date last reviewed. Models become stale as systems evolve. @example "2026-03-01"' },
     participants: { type: "string", description: 'Participants in the exercise. Promote individuals to `node_owned_by_person` edges if participation must be queryable. @example "Alice Chen (security lead), Bob Park (backend engineer), Carol Liu (architect)"' },
@@ -13840,6 +14042,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // UserFlowProperties: User flow.
   user_flow: {
+    flow_type: { type: "string", description: 'What sort of flow this is. Free-form rather than a closed enum, because flow kinds are product-specific and the spec has no complete vocabulary for them. @example "onboarding", "checkout", "recovery", "upgrade"', notes: "`user_flow` otherwise carries only structure (`trigger`, `steps`, `success_state`, `failure_state`) and no classification. The retired `onboarding_flow` type collapsed into `user_flow` along this axis, and its migration default stamps the value so the distinction survives." },
     flow_order: { type: "number", description: "Display order of this flow among sibling flows (0-indexed). The scalar ordering convention shared with `journey_step.step_order` and `journey_action.action_order` (UPG-663 / UPG-674). The free-text `steps` array below still captures the within-flow narrative; this scalar makes the flow itself a deterministically orderable sibling." },
     trigger: { type: "string", description: "Initiating event" },
     steps: { type: "string[]", description: "Ordered steps" },
@@ -13902,7 +14105,8 @@ var UPG_PROPERTY_SCHEMA = {
     severity: {
       type: "assessment",
       scale_id: "severity_5",
-      description: "Categorical severity derived from CVSS. Impact severity (UPGAssessment on the `severity_5` scale). Score alone is insufficient for triage; severity drives filtering and prioritisation. Migrated from the inline `critical|high|medium|low|informational` enum (UPG-579 Option C): map `critical` -> 5, `high` -> 4, `medium` -> 3, `low` -> 2, `informational` -> 1; carry the old word in `label`. @example value 5, label 'Critical', scale_id 'severity_5' (a remotely exploitable, no-auth vuln)",
+      description: "Categorical severity derived from CVSS, as a UPGAssessment on the `severity_5` scale. Score alone is insufficient for triage: severity is what drives filtering and prioritisation. @example value 5, label 'Critical', scale_id 'severity_5' (a remotely exploitable, no-auth vuln)",
+      notes: "Migrated from the inline `critical|high|medium|low|informational` enum (UPG-579 Option C): map `critical` to 5, `high` to 4, `medium` to 3, `low` to 2, `informational` to 1, carrying the old word in `label` so the original vocabulary survives the move.",
       properties: {
         value: { type: "number", description: "The numeric value, used for computation." },
         label: { type: "string", description: "The qualitative label (what the assessor meant)." },
@@ -13974,12 +14178,14 @@ var UPG_PROPERTY_SCHEMA = {
   workspace: {
     visibility: { type: "string", enum: ["private", "shared", "public"], description: "Who can see this workspace" },
     purpose: { type: "string", description: "Free-text description. Pairs with the closed-enum `workspace_purpose`." },
-    workspace_purpose: { type: "string", enum: ["discovery", "planning", "retrospective", "design", "research", "strategy", "general"], description: "Closed-enum classifier. Drives template suggestions and surfaces in workspace browsers. `discovery` = persona/job/opportunity exploration. `planning` = roadmap and decision sessions. `retrospective` = reflection on shipped work. `design` = experience or UI exploration. `research` = organising study data and synthesis. `strategy` = high-level direction setting. `general` = catch-all." },
+    workspace_purpose: { type: "string", enum: ["discovery", "planning", "retrospective", "design", "research", "strategy", "general"], description: "What the workspace is for. Drives template suggestions and surfaces in workspace browsers.", notes: "`discovery` is persona, job and opportunity exploration. `planning` covers roadmap and decision sessions. `retrospective` is reflection on shipped work. `design` is experience or UI exploration. `research` organises study data and synthesis. `strategy` is high-level direction setting. `general` is the catch-all." },
     owner: { type: "string", description: "Workspace owner (handle or email). Display label; canonical owner is `team_owns_workspace` or `persona_owns_workspace`." },
     member_count: { type: "number", description: "Snapshot count. `team_works_in_workspace` edges are the source of truth.", modifier: "derived" },
     archived: { type: "boolean", description: "Archived. Archived workspaces remain queryable but hidden from default views." },
     archived_at: { type: "string", description: "ISO timestamp archived. Pairs with `archived === true`." },
-    icon: { type: "string", description: "Display icon (emoji or icon name)" }
+    icon: { type: "string", description: "Display icon (emoji or icon name)" },
+    retention: { type: "string", enum: ["transient", "durable"], description: "Retention intent. Absent means `transient`.", notes: "A workspace is a free-form thinking space and is transient by default, so the spec makes both intents EXPRESSIBLE and takes no position on which reaches the file. Whether to write a transient canvas at all is a tool decision, and the recommended posture is not to: a scratch canvas nobody named has no business in a shared, git-tracked graph, where it lands in everyone's diff. Writing only `durable` workspaces is what keeps a canonical graph entity comfortable with a transient-by-default object." },
+    canvas: { type: "object", description: "Opaque canvas furniture: the parts of a canvas with no graph referent. Preserved verbatim on round-trip and never interpreted. Tool extension keys are namespaced `<tool>:<key>` with a colon, and no consumer interprets a key it does not own.", notes: "The cut here is UPG principle P14 applied literally. Anything that is a REFERENCE TO A GRAPH NODE is an edge, which is why placed entities ride `workspace_arranges_node` and not this bag: a node id held as a scalar inside a blob is a foreign key in disguise, and a deleted node would leave a stale reference nothing can detect. Anything that is pure UI chrome with no graph referent stays here, because minting `annotation` and `frame` entity types would add catalog surface that is meaningless to every consumer outside the tool that drew it. WHY THE COLON, and why the rule is in the summary rather than buried here. An underscore key is indistinguishable from an ordinary property name, so a migration that targets namespaced keys cannot match it and no validator can detect one that should have been namespaced. That undetectability is why enforcement lives in the type and the documentation instead of in a check: a check would report clean on a bag full of underscore keys, which is worse than no check. Two conventions were already coexisting when this was ruled (`entopo_views` in a live writer, `entopo:view_blocks` in the contract test certifying preservation), which is how a cheap rule becomes a migration. PRESERVATION IS NOT PERMISSION TO RENDER. Preserving every byte says nothing about meaning: a field-measured canvas carried `excluded: true` tombstones, and a consumer that preserved them faithfully while rendering every entry showed the user images they had deleted." }
   }
 };
 function getPropertySchema(entityType) {
@@ -15022,6 +15228,256 @@ var UPG_FRAMEWORKS = [
       ]
     }
   },
+  {
+    "id": "lean-canvas",
+    "name": "Lean Canvas",
+    "version": "1.0.0",
+    "description": "Startup-focused adaptation of the BMC. Replaces partners/resources with problem/solution/unfair advantage.",
+    "category": "business_model",
+    "origin": {
+      "type": "practitioner",
+      "attribution": "Ash Maurya",
+      "description": "Adapted from BMC for startups. Published in Running Lean (O'Reilly). Replaces partners/resources with problem/solution.",
+      "url": "https://leanstack.com/lean-canvas",
+      "year": 2012,
+      "license": "published_methodology"
+    },
+    "tags": [
+      "business_model",
+      "matrix"
+    ],
+    "slots": [
+      {
+        "label": "Problem",
+        "entityTypeId": "need",
+        "description": "Top 3 problems your customers face"
+      },
+      {
+        "label": "Solution",
+        "entityTypeId": "solution",
+        "description": "Top 3 features addressing each problem"
+      },
+      {
+        "label": "Key Metrics",
+        "entityTypeId": "metric",
+        "description": "Key numbers that tell you how your business is doing"
+      },
+      {
+        "label": "Unique Value Prop",
+        "entityTypeId": "value_proposition",
+        "description": "Single, clear, compelling message"
+      },
+      {
+        "label": "Unfair Advantage",
+        "entityTypeId": "capability",
+        "description": "Something that cannot be easily copied"
+      },
+      {
+        "label": "Channels",
+        "entityTypeId": "acquisition_channel",
+        "description": "Path to customers"
+      },
+      {
+        "label": "Customer Segments",
+        "entityTypeId": "persona",
+        "description": "Target customers"
+      },
+      {
+        "label": "Existing Alternatives",
+        "entityTypeId": "competitor",
+        "description": "What do customers use today?"
+      },
+      {
+        "label": "Early Adopters",
+        "entityTypeId": "behavioral_segment",
+        "description": "Your first target customers"
+      },
+      {
+        "label": "Cost Structure",
+        "entityTypeId": "cost_structure",
+        "description": "Customer acquisition costs, hosting, etc."
+      },
+      {
+        "label": "Revenue Streams",
+        "entityTypeId": "revenue_stream",
+        "description": "Revenue model, lifetime value, margins"
+      }
+    ],
+    "data": {
+      "entity_types": [
+        {
+          "type": "need",
+          "role": "bucket"
+        },
+        {
+          "type": "solution",
+          "role": "bucket"
+        },
+        {
+          "type": "value_proposition",
+          "role": "bucket"
+        },
+        {
+          "type": "competitor",
+          "role": "bucket"
+        },
+        {
+          "type": "persona",
+          "role": "bucket"
+        },
+        {
+          "type": "behavioral_segment",
+          "role": "bucket"
+        },
+        {
+          "type": "metric",
+          "role": "bucket"
+        },
+        {
+          "type": "acquisition_channel",
+          "role": "bucket"
+        },
+        {
+          "type": "cost_structure",
+          "role": "bucket"
+        },
+        {
+          "type": "revenue_stream",
+          "role": "bucket"
+        },
+        {
+          "type": "capability",
+          "role": "item"
+        }
+      ],
+      "required_properties": {}
+    },
+    "structure": {
+      "pattern": "matrix"
+    },
+    "presentation": {
+      "layout": {
+        "type": "matrix",
+        "rows": 3,
+        "cols": 4
+      },
+      "sort_by": {
+        "property": "title",
+        "direction": "asc"
+      },
+      "colour_by": "group",
+      "card_fields": [
+        "title",
+        "description"
+      ]
+    },
+    "education": {
+      "purpose": "Capture an entire business model hypothesis on a single page so founders can test assumptions rapidly without writing a full business plan.",
+      "core_question": "What are the riskiest assumptions in our business model, and how can we test them quickly?",
+      "when_to_use": [
+        "You are designing or redesigning how the business creates and captures value",
+        "You need to communicate the business model to stakeholders or investors",
+        "You want to identify risks and assumptions in your business model"
+      ],
+      "when_not_to_use": [
+        "The business model is mature and well-understood by all stakeholders",
+        "You are focused on tactical execution rather than model design"
+      ]
+    }
+  },
+  {
+    "id": "competitive-landscape",
+    "approach_ids": [
+      "inspect"
+    ],
+    "name": "Competitive Landscape",
+    "version": "1.0.0",
+    "description": "Survey the whole competitive environment on one surface: who competes, what they ship, where the market is moving, and how you are positioned within it.",
+    "category": "competitive",
+    "origin": {
+      "type": "custom",
+      "attribution": "The Product Creator",
+      "description": "Original to the Unified Product Graph. Where competitor-profile studies one rival in depth, the landscape holds the market-level view: the competitor set, their features, the trends acting on all of them, and your own positioning read against the whole. Assembled from four entity types the catalog already models rather than adapted from a published methodology.",
+      "license": "open_attribution"
+    },
+    "tags": [
+      "competitive",
+      "matrix"
+    ],
+    "slots": [
+      {
+        "label": "Competitors",
+        "entityTypeId": "competitor",
+        "description": "The rivals in the market you are surveying"
+      },
+      {
+        "label": "Competitor Features",
+        "entityTypeId": "competitor_feature",
+        "description": "What those competitors actually ship"
+      },
+      {
+        "label": "Market Trends",
+        "entityTypeId": "market_trend",
+        "description": "Forces acting on the whole market, not on one rival"
+      },
+      {
+        "label": "Positioning",
+        "entityTypeId": "positioning",
+        "description": "Where you stand relative to the field"
+      }
+    ],
+    "data": {
+      "entity_types": [
+        {
+          "type": "competitor",
+          "role": "item"
+        },
+        {
+          "type": "competitor_feature",
+          "role": "item"
+        },
+        {
+          "type": "market_trend",
+          "role": "item"
+        },
+        {
+          "type": "positioning",
+          "role": "item"
+        }
+      ],
+      "required_properties": {}
+    },
+    "structure": {
+      "pattern": "matrix"
+    },
+    "presentation": {
+      "layout": {
+        "type": "matrix",
+        "rows": 2,
+        "cols": 2
+      },
+      "colour_by": "type",
+      "card_fields": [
+        "title",
+        "description",
+        "status"
+      ]
+    },
+    "education": {
+      "purpose": "Hold the market-level competitive picture in one place: the field of rivals, what they ship, the trends moving the whole category, and your own position read against all three.",
+      "core_question": "What does the field look like from above, and where do we sit in it?",
+      "when_to_use": [
+        "You need the shape of a whole market before choosing which rival to study in depth",
+        "Trends are moving the category and you need them beside the competitor set, not in a separate document",
+        "A positioning statement needs the competitive evidence sitting next to it"
+      ],
+      "when_not_to_use": [
+        "You already know which single rival matters and want depth on them: use competitor-profile",
+        "You are comparing capabilities feature-by-feature against named rivals: use competitive-matrix",
+        "You need to place rivals positionally on two scored axes: use positioning-map"
+      ]
+    }
+  },
   {
     "id": "porter-five-forces",
     "approach_ids": [
@@ -15315,47 +15771,149 @@ var UPG_FRAMEWORKS = [
     }
   },
   {
-    "id": "three-horizons",
+    "id": "product-vision-board",
     "approach_ids": [
       "plan"
     ],
-    "name": "Three Horizons of Growth",
+    "name": "Product Vision Board",
     "version": "1.0.0",
-    "description": "McKinsey's growth framework dividing the portfolio into three time horizons: H1 (core business), H2 (emerging opportunities), H3 (future bets). Ensures balanced investment across today, tomorrow, and the future.",
-    "category": "portfolio",
+    "description": "Roman Pichler's one-page vision canvas. A vision at the top narrows through target group, needs, product and business goals, so the reason for building and the thing being built stay on the same page.",
+    "category": "strategy",
     "origin": {
       "type": "practitioner",
-      "attribution": "McKinsey",
-      "description": 'Introduced by Mehrdad Baghai, Stephen Coley, and David White in "The Alchemy of Growth" (1999, McKinsey). Adapted by many organisations and later by Bill Sharpe for futures thinking.',
-      "url": "https://www.mckinsey.com/business-functions/strategy-and-corporate-finance/our-insights/enduring-ideas-the-three-horizons-of-growth",
-      "year": 1999,
-      "license": "open_attribution"
+      "attribution": "Roman Pichler",
+      "description": 'Created by Roman Pichler as a one-page tool for capturing and sharing a product vision, and published in "Strategize" (2016). The board deliberately keeps the vision, the people it serves, their needs, the product and the business goals in a single vertical read, so a change to any one is visible against the other four.',
+      "license": "published_methodology"
     },
     "tags": [
-      "portfolio",
-      "tree"
+      "strategy",
+      "matrix"
     ],
     "slots": [
       {
-        "label": "Portfolio",
-        "role": "portfolio",
-        "entityTypeId": "portfolio",
-        "description": "Innovation portfolio balanced across three horizons: core performance, emerging growth, and future creation"
+        "label": "Vision",
+        "entityTypeId": "vision",
+        "description": "The long-term change the product exists to bring about"
       },
       {
-        "label": "Product",
-        "role": "product",
-        "entityTypeId": "product",
-        "description": "Product or business unit assigned to a horizon: H1 (defend and extend), H2 (build), or H3 (seed and explore)"
+        "label": "Target Group",
+        "entityTypeId": "persona",
+        "description": "The customers and users the vision is for"
       },
       {
-        "label": "Initiative",
-        "role": "initiative",
-        "entityTypeId": "portfolio",
-        "description": "Growth initiative positioned in a horizon, with appropriate funding model, governance, and success metrics"
+        "label": "Needs",
+        "entityTypeId": "need",
+        "description": "The problem the product solves or the benefit it provides for that group"
       },
       {
-        "label": "Product Area",
+        "label": "Product",
+        "entityTypeId": "solution",
+        "description": "What the product is, and what makes it stand out"
+      },
+      {
+        "label": "Business Goals",
+        "entityTypeId": "outcome",
+        "description": "How the product benefits the company that builds it"
+      }
+    ],
+    "data": {
+      "entity_types": [
+        {
+          "type": "vision",
+          "role": "item"
+        },
+        {
+          "type": "persona",
+          "role": "item"
+        },
+        {
+          "type": "need",
+          "role": "item"
+        },
+        {
+          "type": "solution",
+          "role": "item"
+        },
+        {
+          "type": "outcome",
+          "role": "item"
+        }
+      ],
+      "required_properties": {}
+    },
+    "structure": {
+      "pattern": "matrix"
+    },
+    "presentation": {
+      "layout": {
+        "type": "matrix",
+        "rows": 5,
+        "cols": 1
+      },
+      "colour_by": "type",
+      "card_fields": [
+        "title",
+        "description",
+        "status"
+      ]
+    },
+    "education": {
+      "purpose": "Capture a product vision on one page together with the group it serves, their needs, the product itself and the business goals it advances.",
+      "core_question": "What change are we trying to bring about, for whom, and how does building it pay off?",
+      "when_to_use": [
+        "A new product or a major new direction needs a shared vision before any roadmap exists",
+        "The team can describe what it is building but not why anyone should want it",
+        "Vision, target group and business goals are living in three different documents and drifting apart"
+      ],
+      "when_not_to_use": [
+        "The vision is settled and the open question is sequencing: use goal-oriented-roadmap",
+        "You need the causal chain from vision down to daily work: use strategic-cascade",
+        "The question is which business model captures the value: use business-model-canvas"
+      ]
+    }
+  },
+  {
+    "id": "three-horizons",
+    "approach_ids": [
+      "plan"
+    ],
+    "name": "Three Horizons of Growth",
+    "version": "1.0.0",
+    "description": "McKinsey's growth framework dividing the portfolio into three time horizons: H1 (core business), H2 (emerging opportunities), H3 (future bets). Ensures balanced investment across today, tomorrow, and the future.",
+    "category": "portfolio",
+    "origin": {
+      "type": "practitioner",
+      "attribution": "McKinsey",
+      "description": 'Introduced by Mehrdad Baghai, Stephen Coley, and David White in "The Alchemy of Growth" (1999, McKinsey). Adapted by many organisations and later by Bill Sharpe for futures thinking.',
+      "url": "https://www.mckinsey.com/business-functions/strategy-and-corporate-finance/our-insights/enduring-ideas-the-three-horizons-of-growth",
+      "year": 1999,
+      "license": "open_attribution"
+    },
+    "tags": [
+      "portfolio",
+      "tree"
+    ],
+    "slots": [
+      {
+        "label": "Portfolio",
+        "role": "portfolio",
+        "entityTypeId": "portfolio",
+        "description": "Innovation portfolio balanced across three horizons: core performance, emerging growth, and future creation"
+      },
+      {
+        "label": "Product",
+        "role": "product",
+        "entityTypeId": "product",
+        "description": "Product or business unit assigned to a horizon: H1 (defend and extend), H2 (build), or H3 (seed and explore)"
+      },
+      {
+        "label": "Initiative",
+        "role": "initiative",
+        "entityTypeId": "portfolio",
+        "description": "Growth initiative positioned in a horizon, with appropriate funding model, governance, and success metrics"
+      },
+      {
+        "label": "Product Area",
         "role": "product_area",
         "entityTypeId": "product_area",
         "description": "Product area representing a horizon: core products (H1), adjacent expansions (H2), or experimental ventures (H3)"
@@ -15899,25 +16457,95 @@ var UPG_FRAMEWORKS = [
         "label": "Must-haves",
         "role": "must_have",
         "entityTypeId": "feature",
-        "description": "Expected features: absence causes dissatisfaction"
+        "description": "Expected features: absence causes dissatisfaction",
+        "predicate": [
+          {
+            "scope": "framework",
+            "property": "functional_response",
+            "op": "in",
+            "value": [
+              "i_expect_it",
+              "i_am_neutral",
+              "i_can_tolerate_it"
+            ]
+          },
+          {
+            "scope": "framework",
+            "property": "dysfunctional_response",
+            "op": "eq",
+            "value": "i_dislike_it"
+          }
+        ]
       },
       {
         "label": "Performance",
         "role": "performance",
         "entityTypeId": "feature",
-        "description": "More is better: linear satisfaction increase"
+        "description": "More is better: linear satisfaction increase",
+        "predicate": [
+          {
+            "scope": "framework",
+            "property": "functional_response",
+            "op": "eq",
+            "value": "i_like_it"
+          },
+          {
+            "scope": "framework",
+            "property": "dysfunctional_response",
+            "op": "eq",
+            "value": "i_dislike_it"
+          }
+        ]
       },
       {
         "label": "Delighters",
         "role": "delighter",
         "entityTypeId": "feature",
-        "description": "Unexpected features: presence creates delight"
+        "description": "Unexpected features: presence creates delight",
+        "predicate": [
+          {
+            "scope": "framework",
+            "property": "functional_response",
+            "op": "eq",
+            "value": "i_like_it"
+          },
+          {
+            "scope": "framework",
+            "property": "dysfunctional_response",
+            "op": "in",
+            "value": [
+              "i_expect_it",
+              "i_am_neutral",
+              "i_can_tolerate_it"
+            ]
+          }
+        ]
       },
       {
         "label": "Indifferent",
         "role": "indifferent",
         "entityTypeId": "feature",
-        "description": "Features users don't care about either way"
+        "description": "Features users don't care about either way",
+        "predicate": [
+          {
+            "scope": "framework",
+            "property": "functional_response",
+            "op": "in",
+            "value": [
+              "i_am_neutral",
+              "i_can_tolerate_it"
+            ]
+          },
+          {
+            "scope": "framework",
+            "property": "dysfunctional_response",
+            "op": "in",
+            "value": [
+              "i_am_neutral",
+              "i_can_tolerate_it"
+            ]
+          }
+        ]
       }
     ],
     "data": {
@@ -16324,6 +16952,175 @@ var UPG_FRAMEWORKS = [
       ]
     }
   },
+  {
+    "id": "experiment-tracker",
+    "name": "Experiment Tracker",
+    "version": "1.0.0",
+    "description": "Track experiments from design through execution to results. Velocity-focused.",
+    "category": "validation",
+    "origin": {
+      "type": "practitioner",
+      "description": "Common in growth and product teams running continuous experiments.",
+      "license": "cc_by"
+    },
+    "tags": [
+      "validation",
+      "table"
+    ],
+    "relational": {
+      "spine": "experiment_run",
+      "columns": [
+        {
+          "kind": "field",
+          "id": "experiment",
+          "label": "Experiment",
+          "property": "title",
+          "sortable": true
+        },
+        {
+          "kind": "projection",
+          "id": "hypothesis",
+          "label": "Hypothesis",
+          "path": [
+            {
+              "edge": "experiment_plan_ran_as_experiment_run",
+              "direction": "reverse"
+            },
+            {
+              "edge": "hypothesis_requires_experiment_plan",
+              "direction": "reverse"
+            }
+          ],
+          "fields": [
+            "title"
+          ],
+          "sortable": true
+        },
+        {
+          "kind": "projection",
+          "id": "success_metric",
+          "label": "Success Metric",
+          "path": [
+            {
+              "edge": "experiment_run_measures_metric",
+              "direction": "forward"
+            }
+          ],
+          "fields": [
+            "title",
+            "current_value",
+            "target_value"
+          ]
+        },
+        {
+          "kind": "field",
+          "id": "stage",
+          "label": "Stage",
+          "property": "status"
+        },
+        {
+          "kind": "field",
+          "id": "verdict",
+          "label": "Verdict",
+          "property": "disposition"
+        },
+        {
+          "kind": "projection",
+          "id": "result",
+          "label": "Result",
+          "path": [
+            {
+              "edge": "experiment_run_produces_learning",
+              "direction": "forward"
+            }
+          ],
+          "fields": [
+            "title",
+            "result_direction"
+          ]
+        },
+        {
+          "kind": "projection",
+          "id": "evidence",
+          "label": "Evidence",
+          "path": [
+            {
+              "edge": "experiment_run_yields_evidence",
+              "direction": "forward"
+            }
+          ],
+          "fields": [
+            "title"
+          ]
+        }
+      ],
+      "sort": {
+        "column": "experiment",
+        "direction": "asc"
+      }
+    },
+    "data": {
+      "entity_types": [
+        {
+          "type": "experiment_run",
+          "role": "item"
+        },
+        {
+          "type": "experiment_plan",
+          "role": "item"
+        },
+        {
+          "type": "hypothesis",
+          "role": "item"
+        },
+        {
+          "type": "metric",
+          "role": "item"
+        },
+        {
+          "type": "learning",
+          "role": "item"
+        },
+        {
+          "type": "evidence",
+          "role": "item"
+        }
+      ],
+      "required_properties": {}
+    },
+    "structure": {
+      "pattern": "table"
+    },
+    "presentation": {
+      "layout": {
+        "type": "table",
+        "columns": []
+      },
+      "sort_by": {
+        "property": "title",
+        "direction": "asc"
+      },
+      "colour_by": "type",
+      "card_fields": [
+        "title",
+        "description",
+        "status"
+      ]
+    },
+    "education": {
+      "purpose": "Track all running and completed experiments in one place: hypothesis, method, status, result, learnings. The team builds a cumulative record of validated knowledge.",
+      "core_question": "What experiments are running, what have we learned from completed experiments, and are we applying those learnings to new hypotheses?",
+      "when_to_use": [
+        "You have hypotheses about user needs or solutions that need testing",
+        "You want to reduce risk before committing engineering resources",
+        "The team is debating assumptions that can be tested empirically"
+      ],
+      "when_not_to_use": [
+        "The solution is already validated through real usage data",
+        "Speed of shipping matters more than certainty about assumptions"
+      ]
+    }
+  },
   {
     "id": "hypothesis-board",
     "approach_ids": [
@@ -16650,6 +17447,117 @@ var UPG_FRAMEWORKS = [
       ]
     }
   },
+  {
+    "id": "threat-model-canvas",
+    "approach_ids": [
+      "inspect"
+    ],
+    "name": "Threat Model Canvas",
+    "version": "1.0.0",
+    "description": "One surface for a product's security posture: the threat models in play, the threats and vulnerabilities they name, and the controls, policies and reviews answering them.",
+    "category": "security",
+    "origin": {
+      "type": "custom",
+      "attribution": "The Product Creator",
+      "description": "Original to the Unified Product Graph. Deliberately NOT a STRIDE record: STRIDE is a taxonomy of six threat categories (spoofing, tampering, repudiation, information disclosure, denial of service, elevation of privilege), whereas this canvas lays out the security lifecycle: models, then threats, then vulnerabilities, then the controls, policies and reviews that answer them. A STRIDE record would be a different framework with six slots of one type, and is not this one. Assembled from six entity types the catalog already models.",
+      "license": "open_attribution"
+    },
+    "tags": [
+      "security",
+      "matrix"
+    ],
+    "slots": [
+      {
+        "label": "Threat Models",
+        "entityTypeId": "threat_model",
+        "description": "The modelling exercises themselves: scope, system, assumptions"
+      },
+      {
+        "label": "Threats",
+        "entityTypeId": "threat",
+        "description": "What an adversary could attempt against the system"
+      },
+      {
+        "label": "Vulnerabilities",
+        "entityTypeId": "vulnerability",
+        "description": "Weaknesses that make a threat realisable"
+      },
+      {
+        "label": "Controls",
+        "entityTypeId": "security_control",
+        "description": "Technical and procedural measures that reduce risk"
+      },
+      {
+        "label": "Policies",
+        "entityTypeId": "security_policy",
+        "description": "The standing rules the controls implement"
+      },
+      {
+        "label": "Reviews",
+        "entityTypeId": "security_review",
+        "description": "Assessments that check the posture actually holds"
+      }
+    ],
+    "data": {
+      "entity_types": [
+        {
+          "type": "threat_model",
+          "role": "item"
+        },
+        {
+          "type": "threat",
+          "role": "item"
+        },
+        {
+          "type": "vulnerability",
+          "role": "item"
+        },
+        {
+          "type": "security_control",
+          "role": "item"
+        },
+        {
+          "type": "security_policy",
+          "role": "item"
+        },
+        {
+          "type": "security_review",
+          "role": "item"
+        }
+      ],
+      "required_properties": {}
+    },
+    "structure": {
+      "pattern": "matrix"
+    },
+    "presentation": {
+      "layout": {
+        "type": "matrix",
+        "rows": 2,
+        "cols": 3
+      },
+      "colour_by": "type",
+      "card_fields": [
+        "title",
+        "description",
+        "status"
+      ]
+    },
+    "education": {
+      "purpose": "Hold a product's whole security posture on one surface, so a named threat and the control that answers it are read together rather than tracked in separate systems.",
+      "core_question": "What could go wrong, what makes it possible, and what have we actually put in place against it?",
+      "when_to_use": [
+        "A threat modelling session needs somewhere to land that is not a document nobody reopens",
+        "Controls and policies exist but nobody can point to the threats they answer",
+        "An audit or review asks you to show posture, not just a list of findings"
+      ],
+      "when_not_to_use": [
+        "You want STRIDE's six threat categories specifically. This canvas is a lifecycle, not that taxonomy",
+        "You are triaging a live incident rather than modelling posture",
+        "The work is scoring and ranking risks against each other rather than laying out what exists"
+      ]
+    }
+  },
   {
     "id": "atomic-design",
     "approach_ids": [
@@ -17423,32 +18331,128 @@ var UPG_FRAMEWORKS = [
       "purpose": "Systematically test all 19 traction channels to find the one or two that drive scalable growth, avoiding premature commitment to a favourite channel.",
       "core_question": "Which of the 19 traction channels is our bullseye, the one that works at our current stage and scale?",
       "when_to_use": [
-        "You need to systematically identify and optimise growth levers",
-        "User acquisition, activation, or retention metrics need improvement",
-        "You want to build a structured growth experimentation practice"
+        "You need to systematically identify and optimise growth levers",
+        "User acquisition, activation, or retention metrics need improvement",
+        "You want to build a structured growth experimentation practice"
+      ],
+      "when_not_to_use": [
+        "The product has not yet achieved product-market fit",
+        "Growth would scale problems rather than value"
+      ]
+    }
+  },
+  {
+    "id": "product-led-growth-framework",
+    "approach_ids": [
+      "plan"
+    ],
+    "name": "PLG Framework",
+    "version": "1.0.0",
+    "description": "Product-led go-to-market motion. Free entry gives users access, the aha moment hooks them, they expand usage within their team, and monetisation captures value from power users.",
+    "category": "go_to_market",
+    "origin": {
+      "type": "practitioner",
+      "attribution": "Wes Bush",
+      "description": 'Coined and formalised by Wes Bush in "Product-Led Growth" (2019). The framework describes how the product itself drives acquisition, activation, and expansion, reducing dependence on sales-led motions.',
+      "url": "https://www.productled.com/",
+      "year": 2019,
+      "license": "published_methodology"
+    },
+    "tags": [
+      "go_to_market",
+      "flow"
+    ],
+    "slots": [
+      {
+        "label": "Free Entry",
+        "role": "free_entry",
+        "entityTypeId": "gtm_strategy",
+        "description": "How users access the product for free"
+      },
+      {
+        "label": "Aha Moment",
+        "role": "aha_moment",
+        "entityTypeId": "gtm_strategy",
+        "description": "First experience of core value"
+      },
+      {
+        "label": "Expansion Motion",
+        "role": "expansion_motion",
+        "entityTypeId": "sales_motion",
+        "description": "How usage spreads within accounts"
+      },
+      {
+        "label": "Monetisation Trigger",
+        "role": "monetisation_trigger",
+        "entityTypeId": "gtm_strategy",
+        "description": "When and how to convert to paid"
+      },
+      {
+        "label": "Metric",
+        "role": "metric",
+        "entityTypeId": "metric",
+        "description": "Key metric driving the PLG motion"
+      }
+    ],
+    "data": {
+      "entity_types": [
+        {
+          "type": "gtm_strategy",
+          "role": "item"
+        },
+        {
+          "type": "sales_motion",
+          "role": "item"
+        },
+        {
+          "type": "metric",
+          "role": "item"
+        }
+      ],
+      "required_properties": {}
+    },
+    "structure": {
+      "pattern": "flow"
+    },
+    "presentation": {
+      "layout": {
+        "type": "flow",
+        "direction": "LR"
+      },
+      "colour_by": "status",
+      "card_fields": [
+        "title",
+        "description",
+        "status"
+      ]
+    },
+    "education": {
+      "purpose": "Design the product itself as the primary growth driver (free tier, self-serve onboarding, in-product virality) to reduce dependence on sales-led acquisition.",
+      "core_question": "Can our product acquire, activate, and expand users without human intervention, and where in the loop do we still need sales?",
+      "when_to_use": [
+        "You are launching a new product, feature, or entering a new market",
+        "You need to coordinate cross-functional launch activities",
+        "You want to define target customers, channels, and messaging"
       ],
       "when_not_to_use": [
-        "The product has not yet achieved product-market fit",
-        "Growth would scale problems rather than value"
+        "The product is mature with established distribution channels",
+        "You are iterating on an existing product for existing customers"
       ]
     }
   },
   {
-    "id": "product-led-growth-framework",
+    "id": "gtm-playbook",
     "approach_ids": [
       "plan"
     ],
-    "name": "PLG Framework",
+    "name": "GTM Playbook",
     "version": "1.0.0",
-    "description": "Product-led go-to-market motion. Free entry gives users access, the aha moment hooks them, they expand usage within their team, and monetisation captures value from power users.",
+    "description": "End-to-end go-to-market plan. Covers market analysis, ICP definition, positioning, messaging, channel strategy, launch plan, and success metrics in a sequential flow.",
     "category": "go_to_market",
     "origin": {
       "type": "practitioner",
-      "attribution": "Wes Bush",
-      "description": 'Coined and formalised by Wes Bush in "Product-Led Growth" (2019). The framework describes how the product itself drives acquisition, activation, and expansion, reducing dependence on sales-led motions.',
-      "url": "https://www.productled.com/",
-      "year": 2019,
-      "license": "published_methodology"
+      "description": "Synthesised from go-to-market practice across product marketing, sales, and customer success. The playbook format coordinates all GTM functions into a single executable plan.",
+      "license": "cc_by"
     },
     "tags": [
       "go_to_market",
@@ -17456,34 +18460,34 @@ var UPG_FRAMEWORKS = [
     ],
     "slots": [
       {
-        "label": "Free Entry",
-        "role": "free_entry",
+        "label": "Market Analysis",
         "entityTypeId": "gtm_strategy",
-        "description": "How users access the product for free"
+        "description": "Market sizing and competitive landscape"
       },
       {
-        "label": "Aha Moment",
-        "role": "aha_moment",
-        "entityTypeId": "gtm_strategy",
-        "description": "First experience of core value"
+        "label": "Ideal Customer Profile",
+        "entityTypeId": "ideal_customer_profile",
+        "description": "Ideal customer profile"
       },
       {
-        "label": "Expansion Motion",
-        "role": "expansion_motion",
-        "entityTypeId": "sales_motion",
-        "description": "How usage spreads within accounts"
+        "label": "Positioning",
+        "entityTypeId": "positioning",
+        "description": "How you position against alternatives"
       },
       {
-        "label": "Monetisation Trigger",
-        "role": "monetisation_trigger",
-        "entityTypeId": "gtm_strategy",
-        "description": "When and how to convert to paid"
+        "label": "Messaging",
+        "entityTypeId": "messaging",
+        "description": "Key messages by audience"
       },
       {
-        "label": "Metric",
-        "role": "metric",
-        "entityTypeId": "metric",
-        "description": "Key metric driving the PLG motion"
+        "label": "Launch",
+        "entityTypeId": "launch",
+        "description": "Launch activities and timeline"
+      },
+      {
+        "label": "Sales Motion",
+        "entityTypeId": "sales_motion",
+        "description": "How you will sell"
       }
     ],
     "data": {
@@ -17493,11 +18497,23 @@ var UPG_FRAMEWORKS = [
           "role": "item"
         },
         {
-          "type": "sales_motion",
+          "type": "ideal_customer_profile",
           "role": "item"
         },
         {
-          "type": "metric",
+          "type": "positioning",
+          "role": "item"
+        },
+        {
+          "type": "messaging",
+          "role": "item"
+        },
+        {
+          "type": "launch",
+          "role": "item"
+        },
+        {
+          "type": "sales_motion",
           "role": "item"
         }
       ],
@@ -17519,8 +18535,8 @@ var UPG_FRAMEWORKS = [
       ]
     },
     "education": {
-      "purpose": "Design the product itself as the primary growth driver (free tier, self-serve onboarding, in-product virality) to reduce dependence on sales-led acquisition.",
-      "core_question": "Can our product acquire, activate, and expand users without human intervention, and where in the loop do we still need sales?",
+      "purpose": "Orchestrate every go-to-market activity (messaging, channels, pricing, enablement, launch timeline) into a single executable plan.",
+      "core_question": "Do all go-to-market functions (product, marketing, sales, CS) have a shared plan for how we'll bring this to market?",
       "when_to_use": [
         "You are launching a new product, feature, or entering a new market",
         "You need to coordinate cross-functional launch activities",
@@ -19733,6 +20749,173 @@ var UPG_FRAMEWORKS = [
         "You are in a delivery phase with clear requirements"
       ]
     }
+  },
+  {
+    "id": "assumption-map",
+    "approach_ids": [
+      "reflect"
+    ],
+    "name": "Assumption Map",
+    "version": "1.0.0",
+    "description": "Plot assumptions on axes of uncertainty vs risk. Most risky + most uncertain = test first.",
+    "category": "validation",
+    "origin": {
+      "type": "practitioner",
+      "attribution": "David Bland",
+      "description": "Published in Testing Business Ideas (Wiley). Prioritises which assumptions to validate first.",
+      "url": "https://www.strategyzer.com/books/testing-business-ideas",
+      "year": 2019,
+      "license": "published_methodology"
+    },
+    "tags": [
+      "validation",
+      "quadrant"
+    ],
+    "slots": [
+      {
+        "label": "Test First",
+        "entityTypeId": "assumption",
+        "role": "test_first",
+        "description": "High risk, low confidence: validate immediately",
+        "predicate": [
+          {
+            "scope": "entity",
+            "property": "risk_level",
+            "op": "band",
+            "value": [
+              4,
+              6
+            ]
+          },
+          {
+            "scope": "entity",
+            "property": "confidence",
+            "op": "band",
+            "value": [
+              1,
+              4
+            ]
+          }
+        ]
+      },
+      {
+        "label": "Research",
+        "entityTypeId": "assumption",
+        "role": "research",
+        "description": "Low risk, low confidence: learn more",
+        "predicate": [
+          {
+            "scope": "entity",
+            "property": "risk_level",
+            "op": "band",
+            "value": [
+              1,
+              4
+            ]
+          },
+          {
+            "scope": "entity",
+            "property": "confidence",
+            "op": "band",
+            "value": [
+              1,
+              4
+            ]
+          }
+        ]
+      },
+      {
+        "label": "Monitor",
+        "entityTypeId": "assumption",
+        "role": "monitor",
+        "description": "High risk but well understood: watch closely",
+        "predicate": [
+          {
+            "scope": "entity",
+            "property": "risk_level",
+            "op": "band",
+            "value": [
+              4,
+              6
+            ]
+          },
+          {
+            "scope": "entity",
+            "property": "confidence",
+            "op": "band",
+            "value": [
+              4,
+              6
+            ]
+          }
+        ]
+      },
+      {
+        "label": "Accept",
+        "entityTypeId": "assumption",
+        "role": "accept",
+        "description": "Low risk, high confidence: safe to proceed",
+        "predicate": [
+          {
+            "scope": "entity",
+            "property": "risk_level",
+            "op": "band",
+            "value": [
+              1,
+              4
+            ]
+          },
+          {
+            "scope": "entity",
+            "property": "confidence",
+            "op": "band",
+            "value": [
+              4,
+              6
+            ]
+          }
+        ]
+      }
+    ],
+    "data": {
+      "entity_types": [
+        {
+          "type": "assumption",
+          "role": "item"
+        }
+      ],
+      "required_properties": {}
+    },
+    "structure": {
+      "pattern": "quadrant"
+    },
+    "presentation": {
+      "layout": {
+        "type": "quadrant",
+        "x_axis": "confidence",
+        "y_axis": "risk_level",
+        "x_label": "Confidence",
+        "y_label": "Risk"
+      },
+      "colour_by": "group",
+      "card_fields": [
+        "title",
+        "description"
+      ]
+    },
+    "education": {
+      "purpose": "Plot assumptions on a risk/evidence matrix so teams test the most dangerous unknowns first instead of building on unvalidated beliefs.",
+      "core_question": "Which assumptions carry the most risk and the least evidence? Where do we run experiments first?",
+      "when_to_use": [
+        "You have hypotheses about user needs or solutions that need testing",
+        "You want to reduce risk before committing engineering resources",
+        "The team is debating assumptions that can be tested empirically"
+      ],
+      "when_not_to_use": [
+        "The solution is already validated through real usage data",
+        "Speed of shipping matters more than certainty about assumptions"
+      ]
+    }
   }
 ];
 var UPG_FRAMEWORKS_BY_ID = Object.fromEntries(
@@ -20403,6 +21586,7 @@ var ENTITY_EMOJI = {
   competitor_signal: "\u{1F4E1}",
   compliance_framework: "\u{1F3DF}\uFE0F",
   compliance_requirement: "\u26F2",
+  composition: "\u{1F5BC}\uFE0F",
   constraint: "\u{1F512}",
   contact: "\u{1F4C7}",
   content_calendar: "\u{1F4C5}",
@@ -24480,12 +25664,21 @@ var PORTFOLIO_GUIDE = {
 var WORKSPACE_GUIDE = {
   domain_id: "workspace",
   anchor_entity: "workspace",
-  creation_sequence: ["workspace", "framework_exercise"],
-  patterns: [],
+  creation_sequence: ["workspace", "framework_exercise", "composition"],
+  patterns: [
+    {
+      name: "Canvas to published view",
+      description: "A workspace arranges the entities being thought about, produces the composition published from it, and the composition names what it focuses on so the published view stays answerable to the graph",
+      entity_types: ["workspace", "composition"],
+      edge_chain: ["workspace_arranges_node", "workspace_produced_node", "composition_focuses_node"]
+    }
+  ],
   required_bridges: [],
   anti_patterns: [
     { description: "Workspaces are containers for exploration: do not over-structure them" },
-    { description: "Workspace content is transient by default: promote discoveries to the graph, do not leave them in the workspace" }
+    { description: "Workspace content is transient by default: promote discoveries to the graph, do not leave them in the workspace" },
+    { description: "Treating a canvas arrangement as structure: a workspace_arranges_node edge says where a card sits, never what contains what. The arranged entity keeps its real parent" },
+    { description: "Writing every scratch canvas into a shared graph: only a workspace someone deliberately kept (retention: durable) belongs in a file other people pull" }
   ]
 };
 var FOUNDATIONS_GUIDE = {
@@ -27454,7 +28647,7 @@ var UPG_ANTI_PATTERNS = [
     id: "contended-surface-without-arbitration",
     since: "0.27.0",
     name: "Contended surface without arbitration",
-    description: 'At least one surface in this graph has no recorded answer to "who wins here, and why". Either it holds more occupants than its stated `capacity` allows (or holds several while stating no limit at all) and carries no arbitration_rule, or it admits through arbitration_state that the answer is absent (`none`) or accidental (`safe_by_coincidence`). Left unrecorded, that answer lives in whoever remembers the last argument.',
+    description: 'At least one surface has no recorded answer to "who wins here, and why". Either it holds more occupants than its stated `capacity` allows (or holds several while stating no limit) and carries no arbitration_rule, or it admits through arbitration_state that the answer is absent (`none`) or accidental (`safe_by_coincidence`). Unrecorded, that answer lives in whoever remembers the last argument.',
     // 0.28.0 (feedback 852a9721, from a 30-surface field audit). Three changes,
     // each earned by a reported false positive or a reported blind spot:
     //
@@ -27548,12 +28741,26 @@ var UPG_ANTI_PATTERNS = [
     // the natural move if the ordering detector is ever minted; it is not worth a
     // breaking property change before then.
     //
-    // STILL OPEN (banked at 0.28.0, deliberately NOT changed here): a `chained`
-    // slot that honestly declares `arbitration_state: 'none'` re-fires through
-    // branch (c), which carries no chained exemption. Current guidance stands:
-    // leave `arbitration_state` unset on chained surfaces. Changing (b)/(c) was
-    // out of scope for this release and still awaits the field confirmation the
-    // reporter will produce populating their 14 chained slots.
+    // CLOSED (banked at 0.28.0, field-confirmed and resolved here): a `chained`
+    // slot that honestly declared `arbitration_state: 'none'` used to re-fire
+    // through branch (c), which carries no chained exemption. The field
+    // confirmation arrived from a second reporter whose census left the state
+    // unset on every one of its chained frames and named this branch as the
+    // reason. THE FIX WAS THE VOCABULARY, NOT THE DETECTOR. Branch (c) matches
+    // the literal string 'none', so the new fifth `SurfaceArbitrationState`
+    // member `no_contention_by_design` never matches it and NOTHING in this
+    // file, the evaluator, or the collector changed.
+    //
+    // Exempting `chained` from (c) was the alternative and it lost on both
+    // correctness and cost. Correctness: `none` is defined as "nobody ever
+    // decided", which is FALSE on a chained shell that has no decision to make,
+    // and silencing a check on a false statement is worse than the empty field
+    // it replaces. Cost: `evaluateEntityCount`'s except form covers the
+    // PRESENCE filter only; the value-keyed path is a bare indexed lookup with
+    // no exception arm, so giving it one means a parallel derived spec set, a
+    // new collector aggregate keyed by (type, property, value, except_property,
+    // except_value), the derivation walk, and its tests. That is the whole
+    // 0.28.0 evaluator rider again, spent to make a false statement quiet.
     structured_condition: {
       operator: "and",
       checks: [
@@ -27606,7 +28813,23 @@ var UPG_ANTI_PATTERNS = [
       ]
     },
     why_it_matters: "Contention over a UI place is settled every time it comes up, and an unrecorded settlement is re-argued at the next feature. The cost is paid in repeated decisions, not in a visible defect. A surface that is safe only by coincidence pays it all at once instead, the first time an occupant is added.",
-    remediation: "The violation names the offending surfaces in `target_node_ids`; start there rather than re-reading the whole roster. Read `arbitration_state` first: it says what the work actually is. `enforced_undocumented` means the rule already exists in code and needs transcribing into `arbitration_rule`: ten minutes, no meeting. `none` means nobody has decided and someone has to. `safe_by_coincidence` means nothing is enforcing anything and the surface only looks settled; that one wants a guard in code, not just prose. If a flagged surface genuinely holds everything it was designed to hold, the honest fix is to state its `capacity`, not to invent a rule: a surface whose occupancy is at or below a stated capacity is partitioned rather than contended, and it stops firing. Where a design system already answers the question, link the source with `surface_governed_by_design_guideline`. Surfaces whose occupants wrap one another rather than compete should declare `composition_mode: 'chained'`, which exempts them: that is a factual claim about how the code composes, not a way to quiet the check.",
+    // Remediation is deliberately the ACTIONABLE CORE only. It is read by
+    // someone who has already been told there is a problem and now needs the
+    // next move, so rationale in it is strictly in the way. The reasoning that
+    // used to live here (why transcription is ten minutes rather than a
+    // meeting, why safe_by_coincidence is the dangerous state, why declaring
+    // capacity is the honest fix rather than inventing a rule, and why the
+    // chained exemption is a factual claim rather than a mute button) is all
+    // above in this comment block, which is where a reader who wants it looks.
+    remediation: (
+      // Remediation is read by someone already told there is a problem and now
+      // wanting the action, so rationale is strictly in the way. The reasoning
+      // trimmed out in 0.31.0: a surface at its designed capacity should state
+      // that capacity rather than invent an arbitration rule it does not need,
+      // and leaving the state empty on a chained surface reads as unassessed
+      // rather than as "nothing to arbitrate".
+      "Start from `target_node_ids`, then read `arbitration_state`: `enforced_undocumented` needs the rule transcribed into `arbitration_rule`, `none` needs a decision, `safe_by_coincidence` needs a guard in code. A surface holding all it was designed to should state its `capacity`. Occupants that wrap rather than compete declare `composition_mode: 'chained'` with `arbitration_state: 'no_contention_by_design'`."
+    ),
     stages: ["build", "beta", "launch", "growth", "mature", "maintenance"],
     severity: "medium",
     source: { kind: "fundamental" }
@@ -30578,6 +31801,63 @@ var UPG_STRUCTURE_PATTERNS = [
   "flow"
 ];
 
+// src/frameworks/relational-paths.ts
+function resolveRelationalPath(spine, path, catalog = UPG_EDGE_CATALOG) {
+  const steps = [];
+  if (path.length === 0) {
+    return { steps, endpoint: null, reason: "path is empty; a projection must declare at least one step", failedAt: 0 };
+  }
+  let current = spine;
+  for (let i = 0; i < path.length; i++) {
+    const step = path[i];
+    const entry = catalog[step.edge];
+    if (!entry) {
+      return {
+        steps,
+        endpoint: null,
+        failedAt: i,
+        reason: `unknown edge type "${step.edge}" \u2014 not in the UPG edge catalog`
+      };
+    }
+    if (step.direction !== "forward" && step.direction !== "reverse") {
+      return {
+        steps,
+        endpoint: null,
+        failedAt: i,
+        reason: `step direction must be "forward" or "reverse", got "${String(step.direction)}"`
+      };
+    }
+    const entersAt = step.direction === "forward" ? entry.source_type : entry.target_type;
+    const landsOn = step.direction === "forward" ? entry.target_type : entry.source_type;
+    if (entersAt !== current) {
+      return {
+        steps,
+        endpoint: null,
+        failedAt: i,
+        reason: `step ${i} ("${step.edge}" ${step.direction}) enters at "${entersAt}" but the traversal is at "${current}". The edge is declared ${entry.source_type} -> ${entry.target_type}; traversing it ${step.direction} requires being at "${entersAt}".`
+      };
+    }
+    steps.push({ from: current, to: landsOn });
+    current = landsOn;
+  }
+  return { steps, endpoint: current, reason: null, failedAt: -1 };
+}
+function relationalCoveredEntityTypes(fw) {
+  const covered = /* @__PURE__ */ new Set();
+  const rel = fw.relational;
+  if (!rel) return covered;
+  covered.add(rel.spine);
+  for (const column of rel.columns) {
+    if (column.kind !== "projection") continue;
+    const resolved = resolveRelationalPath(rel.spine, column.path);
+    for (const step of resolved.steps) {
+      covered.add(step.from);
+      covered.add(step.to);
+    }
+  }
+  return covered;
+}
+
 // src/frameworks/validate.ts
 function validateUPGFramework(framework) {
   const errors = [];
@@ -30682,6 +31962,25 @@ function validateUPGFramework(framework) {
       }
     }
   }
+  if (f.relational !== void 0) {
+    if (typeof f.relational !== "object" || f.relational === null || Array.isArray(f.relational)) {
+      errors.push('"relational" must be an object when present');
+    } else {
+      const rel = f.relational;
+      errors.push(...validateRelationalSurface(rel));
+      if (Array.isArray(f.slots) && f.slots.length > 0) {
+        warnings.push(
+          '"relational" and "slots" are both declared. `relational` is authoritative for a join surface; slots cannot express an edge path and will drift. Remove "slots" from this framework.'
+        );
+      }
+      const presLayout = f.presentation?.layout;
+      if (presLayout?.type === "table" && Array.isArray(presLayout.columns) && presLayout.columns.length > 0) {
+        errors.push(
+          `"presentation.layout.columns" declares ${presLayout.columns.length} columns, but "relational" is the authoritative roster for a join surface. Empty the presentation columns; do not maintain both.`
+        );
+      }
+    }
+  }
   if (!f.education || typeof f.education !== "object") {
     errors.push('"education" is required and must be an object');
   } else {
@@ -30699,8 +31998,144 @@ function validateUPGFramework(framework) {
       errors.push('"education.when_not_to_use" is required and must be an array');
     }
   }
+  validateSlotPredicates(f.slots, errors);
   return { valid: errors.length === 0, errors, warnings };
 }
+var PREDICATE_SCOPES = ["entity", "framework"];
+var PREDICATE_OPS = ["eq", "in", "gte", "lt", "band"];
+function admits(atom) {
+  switch (atom.op) {
+    case "eq":
+      return { kind: "discrete", values: [atom.value] };
+    case "in":
+      return { kind: "discrete", values: atom.value };
+    case "gte":
+      return { kind: "interval", lo: atom.value, hi: Number.POSITIVE_INFINITY };
+    case "lt":
+      return { kind: "interval", lo: Number.NEGATIVE_INFINITY, hi: atom.value };
+    case "band":
+      return { kind: "interval", lo: atom.value[0], hi: atom.value[1] };
+  }
+}
+function atomsCannotBothHold(a, b) {
+  const x = admits(a);
+  const y = admits(b);
+  if (x.kind === "discrete" && y.kind === "discrete") {
+    return !x.values.some((v) => y.values.includes(v));
+  }
+  if (x.kind === "interval" && y.kind === "interval") {
+    return !(x.lo < y.hi && y.lo < x.hi);
+  }
+  const set = x.kind === "discrete" ? x : y;
+  const range = x.kind === "interval" ? x : y;
+  return !set.values.some((v) => typeof v === "number" && v >= range.lo && v < range.hi);
+}
+function predicatesProvablyDisjoint(a, b) {
+  for (const atomA of a) {
+    for (const atomB of b) {
+      if (atomA.scope === atomB.scope && atomA.property === atomB.property && atomsCannotBothHold(atomA, atomB)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function parseAtom(atom, where, errors) {
+  if (!atom || typeof atom !== "object" || Array.isArray(atom)) {
+    errors.push(`${where} must be an object`);
+    return null;
+  }
+  const a = atom;
+  let ok = true;
+  if (typeof a.scope !== "string" || !PREDICATE_SCOPES.includes(a.scope)) {
+    errors.push(`${where}.scope must be one of: ${PREDICATE_SCOPES.join(", ")}`);
+    ok = false;
+  }
+  if (typeof a.property !== "string" || a.property.length === 0) {
+    errors.push(`${where}.property is required and must be a non-empty string`);
+    ok = false;
+  }
+  if (typeof a.op !== "string" || !PREDICATE_OPS.includes(a.op)) {
+    errors.push(`${where}.op must be one of: ${PREDICATE_OPS.join(", ")}`);
+    return null;
+  }
+  switch (a.op) {
+    case "eq":
+      if (!["string", "number", "boolean"].includes(typeof a.value)) {
+        errors.push(`${where}.value must be a string, number, or boolean for op "eq"`);
+        ok = false;
+      }
+      break;
+    case "in":
+      if (!Array.isArray(a.value) || a.value.length === 0 || !a.value.every((v) => typeof v === "string" || typeof v === "number")) {
+        errors.push(`${where}.value must be a non-empty array of strings or numbers for op "in"`);
+        ok = false;
+      }
+      break;
+    case "gte":
+    case "lt":
+      if (typeof a.value !== "number" || !Number.isFinite(a.value)) {
+        errors.push(`${where}.value must be a finite number for op "${a.op}"`);
+        ok = false;
+      }
+      break;
+    case "band":
+      if (!Array.isArray(a.value) || a.value.length !== 2 || !a.value.every((v) => typeof v === "number" && Number.isFinite(v))) {
+        errors.push(`${where}.value must be a [min, max] pair of finite numbers for op "band"`);
+        ok = false;
+      } else if (a.value[0] >= a.value[1]) {
+        errors.push(
+          `${where}.value is an empty band: min (${a.value[0]}) must be less than max (${a.value[1]}). The interval is half-open [min, max)`
+        );
+        ok = false;
+      }
+      break;
+  }
+  return ok ? a : null;
+}
+function validateSlotPredicates(slots, errors) {
+  if (!Array.isArray(slots)) return;
+  const zones = [];
+  slots.forEach((slot, i) => {
+    if (!slot || typeof slot !== "object") return;
+    const s = slot;
+    if (s.predicate === void 0 || s.predicate === null) return;
+    const label = typeof s.label === "string" && s.label.length > 0 ? ` ("${s.label}")` : "";
+    const where = `"slots[${i}]${label}.predicate"`;
+    if (!Array.isArray(s.predicate)) {
+      errors.push(
+        `${where} must be an array of atoms. A slot's membership rule is a conjunction, even when it has one atom`
+      );
+      return;
+    }
+    if (s.predicate.length === 0) {
+      errors.push(
+        `${where} must not be empty. A zero-atom predicate matches every entity, which is a catch-all cell \u2014 declare the property that decides membership`
+      );
+      return;
+    }
+    const atoms = s.predicate.map((atom, j) => parseAtom(atom, `${where}[${j}]`, errors));
+    if (atoms.some((a) => a === null)) return;
+    zones.push({
+      where: `slots[${i}]${label}`,
+      entityTypeId: typeof s.entityTypeId === "string" ? s.entityTypeId : null,
+      predicate: atoms
+    });
+  });
+  for (let i = 0; i < zones.length; i++) {
+    for (let j = i + 1; j < zones.length; j++) {
+      const a = zones[i];
+      const b = zones[j];
+      if (a.entityTypeId && b.entityTypeId && a.entityTypeId !== b.entityTypeId) continue;
+      if (predicatesProvablyDisjoint(a.predicate, b.predicate)) continue;
+      const shared = a.predicate.filter((x) => b.predicate.some((y) => y.scope === x.scope && y.property === x.property)).map((x) => `${x.scope}.${x.property}`);
+      const hint = shared.length ? `They constrain the same properties (${[...new Set(shared)].join(", ")}) without separating on any of them` : `They constrain no property in common, so an entity can satisfy both`;
+      errors.push(
+        `"${a.where}" and "${b.where}" have predicates that are not provably disjoint, so an entity could land in both zones. ${hint}. Add an atom that separates them \u2014 for example, a value range on one property that the other excludes`
+      );
+    }
+  }
+}
 function validateExpression(expr) {
   if (expr.trim().length === 0) {
     return "Expression must not be empty";
@@ -30720,6 +32155,122 @@ function validateExpression(expr) {
   }
   return null;
 }
+function validateRelationalSurface(rel) {
+  const errors = [];
+  const spine = rel.spine;
+  if (!spine || typeof spine !== "string") {
+    errors.push('"relational.spine" is required and must be a string (the entity type whose instances are the rows)');
+  }
+  if (!Array.isArray(rel.columns) || rel.columns.length === 0) {
+    errors.push('"relational.columns" is required and must be a non-empty array');
+    return errors;
+  }
+  const seenIds = /* @__PURE__ */ new Set();
+  for (let i = 0; i < rel.columns.length; i++) {
+    const col = rel.columns[i];
+    const at = `"relational.columns[${i}]"`;
+    if (!col || typeof col !== "object" || Array.isArray(col)) {
+      errors.push(`${at} must be an object`);
+      continue;
+    }
+    const c = col;
+    if (!c.id || typeof c.id !== "string") {
+      errors.push(`${at}.id is required and must be a string`);
+    } else if (seenIds.has(c.id)) {
+      errors.push(`${at}.id "${c.id}" is duplicated; column ids must be unique within a surface`);
+    } else {
+      seenIds.add(c.id);
+    }
+    if (!c.label || typeof c.label !== "string") {
+      errors.push(`${at}.label is required and must be a string`);
+    }
+    switch (c.kind) {
+      case "field": {
+        if (!c.property || typeof c.property !== "string") {
+          errors.push(`${at}.property is required on a field column and must be a string`);
+        }
+        if ("entityTypeId" in c) {
+          errors.push(
+            `${at} is a field column and must NOT declare "entityTypeId" \u2014 its entity is the spine by definition. A field column that names a type is the slot-forced shape this block replaces.`
+          );
+        }
+        if ("path" in c) {
+          errors.push(`${at} is a field column and must NOT declare "path"; use kind:"projection" to traverse edges`);
+        }
+        break;
+      }
+      case "computed": {
+        if (!c.expression || typeof c.expression !== "string") {
+          errors.push(`${at}.expression is required on a computed column and must be a string`);
+        } else {
+          const exprError = validateExpression(c.expression);
+          if (exprError) errors.push(`${at}.expression: ${exprError}`);
+        }
+        break;
+      }
+      case "projection": {
+        if (!Array.isArray(c.path) || c.path.length === 0) {
+          errors.push(
+            `${at}.path is required on a projection column and must be a non-empty array of { edge, direction } steps`
+          );
+        } else {
+          let stepShapeOk = true;
+          for (let s = 0; s < c.path.length; s++) {
+            const step = c.path[s];
+            if (!step || typeof step !== "object" || Array.isArray(step)) {
+              errors.push(`${at}.path[${s}] must be an object { edge, direction }`);
+              stepShapeOk = false;
+              continue;
+            }
+            const st = step;
+            if (!st.edge || typeof st.edge !== "string") {
+              errors.push(`${at}.path[${s}].edge is required and must be a string`);
+              stepShapeOk = false;
+            }
+            if (st.direction !== "forward" && st.direction !== "reverse") {
+              errors.push(
+                `${at}.path[${s}].direction is required and must be "forward" or "reverse" (never inferred)`
+              );
+              stepShapeOk = false;
+            }
+          }
+          if (stepShapeOk && typeof spine === "string") {
+            const resolved = resolveRelationalPath(spine, c.path);
+            if (resolved.reason) {
+              errors.push(`${at}.path does not compose from spine "${spine}": ${resolved.reason}`);
+            }
+          }
+        }
+        if (!Array.isArray(c.fields) || c.fields.length === 0) {
+          errors.push(`${at}.fields is required on a projection column and must be a non-empty array of property keys`);
+        }
+        if (c.limit !== void 0 && (typeof c.limit !== "number" || !Number.isInteger(c.limit) || c.limit < 1)) {
+          errors.push(`${at}.limit must be a positive integer when present (it truncates rendering, never membership)`);
+        }
+        break;
+      }
+      default:
+        errors.push(`${at}.kind must be one of: field, computed, projection. Got "${String(c.kind)}"`);
+    }
+  }
+  const sort = rel.sort;
+  if (!sort || typeof sort !== "object" || Array.isArray(sort)) {
+    errors.push('"relational.sort" is required and must be an object { column, direction }');
+  } else {
+    const s = sort;
+    if (!s.column || typeof s.column !== "string") {
+      errors.push('"relational.sort.column" is required and must be a string (a column id)');
+    } else if (seenIds.size > 0 && !seenIds.has(s.column)) {
+      errors.push(
+        `"relational.sort.column" is "${s.column}", which is not a declared column id. Declared ids: ${[...seenIds].join(", ")}`
+      );
+    }
+    if (s.direction !== "asc" && s.direction !== "desc") {
+      errors.push('"relational.sort.direction" is required and must be "asc" or "desc"');
+    }
+  }
+  return errors;
+}
 
 // src/format/canonical.ts
 import * as nodeCrypto from "crypto";
@@ -30850,12 +32401,13 @@ function canonicalProduct(product) {
 function effectiveRootProduct(doc) {
   const node = doc.nodes?.find((n) => n.type === "product" && n.id === doc.product.id);
   if (!node) return doc.product;
+  const propStage = node.properties?.stage;
+  const nodeStage = (typeof propStage === "string" ? propStage : void 0) ?? node.status;
   return {
     ...doc.product,
     title: node.title ?? doc.product.title,
     description: node.description ?? doc.product.description,
-    // A product's lifecycle status IS its stage, the same axis (grammar/lifecycles).
-    stage: node.status ?? doc.product.stage
+    stage: nodeStage ?? doc.product.stage
   };
 }
 function singleBody(doc) {
@@ -31101,7 +32653,7 @@ function checkHeaderSealText(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.30.0";
+var UPG_VERSION = "0.31.0";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -31276,6 +32828,7 @@ export {
   USERS_NEEDS_PLAYBOOK,
   UnknownEntityTypeError,
   VARIES_BY_EDGE,
+  WORKSPACE_ARRANGEMENT_EDGE_PROPERTY_SCHEMA,
   backfillSlug,
   buildTypeAliases,
   canBeChildOf,
@@ -31391,14 +32944,17 @@ export {
   normalizeDocument,
   parseUpg,
   pickCanonicalEdge,
+  predicatesProvablyDisjoint,
   presenceExceptKey,
   projectGraph,
   readActiveWhen,
   readStringArray,
+  relationalCoveredEntityTypes,
   resolveAllEdges,
   resolveContainmentEdge,
   resolveEntityType,
   resolveLabel,
+  resolveRelationalPath,
   resolveSlugCollision,
   resolveTreePatternEdges,
   ringOrderedDomainIds,