@unified-product-graph/core 0.33.0 → 0.34.0

package/dist/index.js

@@ -2397,6 +2397,51 @@ var UPG_EDGE_CATALOG = {
   // evidence co-reside), so NOT cross_product_eligible.
   document_contains_quote: { forward_verb: "contains", reverse_verb: "contained_in", classification: "semantic", source_type: "document", target_type: "quote" },
   document_contains_observation: { forward_verb: "contains", reverse_verb: "contained_in", classification: "semantic", source_type: "document", target_type: "observation" },
+  /**
+   * A document EMBEDS this node's live value at a position in its prose.
+   *
+   * @remarks
+   * NOT `describes`. `document_describes_persona` says the document is ABOUT the
+   * persona. Transclusion says the document RENDERS that node where the prose
+   * sits, so the value a reader sees is the node's current value rather than a
+   * copy taken when the sentence was written. A PRD that transcludes a metric is
+   * not "about" the metric, and collapsing the two would lose the only property
+   * transclusion is bought for: current by construction. The nine-member
+   * `document_describes_*` family is untouched and keeps its meaning.
+   *
+   * POLYMORPHIC because the target set is genuinely open. Anything renderable can
+   * be embedded, and the nine enumerated describe-targets are none of `metric`,
+   * `research_study`, `specification` or `architecture_decision`, which is what
+   * 65% of measured documents carrying zero outbound edges were reaching for.
+   *
+   * THE ANCHOR BINDING (normative). `@unified-product-graph/markdown` already
+   * parses an inline reference form and records the source line of every
+   * occurrence: `[[type:id]]`, `[[type:id|label]]`, `[[type:id|k:v|...]]`,
+   * `[[+type:id]]` for creation, and `[[type:id@product]]` across products. The
+   * grammar is published as Appendix F of the specification paper. The rule that
+   * was missing, and is stated here: an anchor appearing in the body of a
+   * `document` IS a transclusion anchor, and a conformant parser WRITES this edge
+   * beside it. Anchor and edge are one fact recorded twice, so they must be
+   * written together or they drift.
+   *
+   * NO POSITION PROPERTY, deliberately. The obvious `anchor_line` is the most
+   * volatile value a text document has: every insertion above moves every anchor
+   * below, so a stored line number is wrong after the next paragraph and nothing
+   * reports the drift. The anchor IS the position, and it lives in the prose
+   * where ordinary editing moves it for free. What the law asks is that the edge
+   * be written BESIDE the anchor, which is a write-time discipline rather than a
+   * stored field.
+   *
+   * `deliberate_only`, and the 0.33.0 trap is why that is safe here. Flagging a
+   * widened edge `deliberate_only` silently switched five adapters off in the
+   * last release, two of them under a green suite. The rule that came out of it:
+   * an adapter reading an explicit field the SOURCE stores carries an authored
+   * fact rather than an inferred one and must emit deliberate-only edges
+   * EXPLICITLY. A `[[type:id]]` anchor is as explicit as a source gets, because a
+   * person typed it, so the markdown emitter keys on the ANCHOR and never on the
+   * `node` wildcard. No generic pair-resolution path may ever produce one.
+   */
+  document_transcludes_node: { forward_verb: "transcludes", reverse_verb: "transcluded_in", classification: "semantic", source_type: "document", target_type: "node", deliberate_only: true },
   // 5.3 Customer Education & Training Domain
   product_educates_via_education_program: { forward_verb: "educates_via", reverse_verb: "educates", classification: "hierarchy", source_type: "product", target_type: "education_program" },
   education_program_teaches_via_tutorial: { forward_verb: "teaches_via", reverse_verb: "teaches", classification: "hierarchy", source_type: "education_program", target_type: "tutorial" },
@@ -2462,10 +2507,10 @@ var UPG_EDGE_CATALOG = {
   // and G2b is not engaged.
   // Membership is UNQUALIFIED: no role property on the edge. `role` is already an
   // entity type with team_staffed_with_role, so a role string here would be a
-  // second role model beside a node type. The consequence is stated rather than
-  // hidden: the graph can say a team has a slot and that a person is on the team,
-  // and not that the person fills the slot. `person_holds_role` is banked, with
-  // its condition the first field graph carrying both where the join is asked for.
+  // second role model beside a node type. The consequence that used to follow is
+  // now closed rather than accepted: the graph can say a team has a slot, that a
+  // person is on the team, AND that the person fills the slot, the last through
+  // `person_holds_role` (0.34.0) rather than through a qualifier here.
   //
   // Neither is cross_product_eligible: `person` is not portfolio_shared, so the
   // 0.18.0 both-endpoints gate rejects the flag regardless of any team-scoping
@@ -2486,6 +2531,41 @@ var UPG_EDGE_CATALOG = {
   // the person / team / department triangle is decided once rather than three
   // times.
   person_reports_to_person: { forward_verb: "reports_to", reverse_verb: "has_report", classification: "semantic", source_type: "person", target_type: "person" },
+  // MINTED 0.34.0 on a grammar-versus-catalog inconsistency readable entirely
+  // inside this package, NOT on the field condition the 0.33.0 bank named. That
+  // condition is still unmet and saying so is the honest framing: both org edges
+  // exist in exactly one graph and it is the saturation fixture, whose person set
+  // contains teams mistyped as people. What replaced it is stronger on its own
+  // terms because it is checkable and adoption-independent:
+  //
+  //   `role`'s lifecycle terminates at `filled` and `vacant`, and `filled` is
+  //   described "Role is staffed." `team_staffed_with_role` runs team -> slot.
+  //   `person_member_of_team` runs person -> team. NOTHING connected a person to
+  //   a role. So a graph could legally mark a role `filled` and no edge in the
+  //   catalog could say by whom.
+  //
+  // A terminal lifecycle phase that no edge can substantiate is dead schema, and
+  // it is worse than a phantom edge name: a phantom is inert, while `filled` is a
+  // value graphs will actually carry. Same class as the anti-pattern entry that
+  // instructed users toward an edge the catalog refused, which is what minted
+  // `person_reports_to_person` one release ago.
+  //
+  // `semantic`, not `cross-domain`. `person`, `role` and `team` are one domain
+  // (domains.ts, team_org), and T1.7 forbids new same-domain cross-domain edges.
+  // This is the third member of that triangle and it is decided on exactly the
+  // ground the other two were decided on mid-build at 0.33.0.
+  //
+  // Direction is person -> role, matching both 0.33.0 person edges, so the
+  // containment reading stays UNAVAILABLE rather than merely unchosen and
+  // UPG_VALID_CHILDREN is untouched. `role_filled_by_person` would source the
+  // edge on the slot, which reads as the slot owning the person.
+  //
+  // Unqualified, for the reason the membership edge above gives: `role` is a type,
+  // not a string, so a qualifier here would be a second role model.
+  //
+  // Not cross_product_eligible: `person` is not portfolio_shared, so the 0.18.0
+  // both-endpoints gate rejects the flag regardless.
+  person_holds_role: { forward_verb: "holds", reverse_verb: "held_by", classification: "semantic", source_type: "person", target_type: "role" },
   team_staffed_with_role: { forward_verb: "staffed_with", reverse_verb: "staffed_in", classification: "hierarchy", source_type: "team", target_type: "role" },
   team_targets_team_okr: { forward_verb: "targets", reverse_verb: "targeted_by", classification: "hierarchy", source_type: "team", target_type: "team_okr" },
   team_reflects_in_retrospective: { forward_verb: "reflects_in", reverse_verb: "reflects", classification: "hierarchy", source_type: "team", target_type: "retrospective" },
@@ -3856,8 +3936,51 @@ var UPG_POLYMORPHIC_EDGE_KEYS = [
   // Project membership (0.33.0, widened from project_delivers_epic):
   // endpoint-polymorphic over the work-item set {feature, epic, user_story, task,
   // bug}. Same construction and same reasoning as the cadence edge above.
-  "project_delivers_work_item"
+  "project_delivers_work_item",
+  // Document transclusion (0.34.0): a document embeds any renderable node's live
+  // value at a position in its prose. Open by nature rather than by an
+  // enumeration nobody wanted to write out.
+  "document_transcludes_node"
 ];
+var UPG_POLYMORPHIC_EDGE_FAMILIES = {
+  "universal semantic verbs": ["node_informs_node", "node_constrains_node", "node_inspires_node"],
+  "decision-to-anything": ["decision_influences_node", "decision_constrained_by_node", "decision_produces_node"],
+  "universal ownership": [
+    "node_owned_by_team",
+    "node_owned_by_role",
+    "node_owned_by_stakeholder",
+    "node_owned_by_department",
+    "node_owned_by_person"
+  ],
+  "universal architecture references": ["node_belongs_to_bounded_context"],
+  "framework exercises": ["framework_exercise_includes_node"],
+  "universal classification": ["node_classified_as_classification_value"],
+  "work-item issue links": [
+    "work_item_blocks_work_item",
+    "work_item_relates_to_work_item",
+    "work_item_duplicates_work_item"
+  ],
+  "workspace provenance": ["workspace_produced_node"],
+  "canvas arrangement and published-view focus": ["workspace_arranges_node", "composition_focuses_node"],
+  "benchmark subject": ["eval_benchmark_measures_node"],
+  // 0.32.0. Assignment is its OWN family and deliberately not a member of
+  // 'universal ownership': keeping them apart in this partition is the same
+  // ruling the edge itself makes, so a future author who merges them here is
+  // making that decision visibly rather than by tidying a list.
+  "universal assignment": ["node_assigned_to_person"],
+  "capture subject": ["capture_renders_node"],
+  "cadence scheduling": ["planning_cycle_schedules_work_item"],
+  // 0.33.0. Project membership is its own family and deliberately not a member
+  // of 'cadence scheduling', even though both range over the same work-item set:
+  // a cycle SCHEDULES work in time and a project REFERENCES the work it delivers,
+  // and merging them here would quietly assert those are one relation.
+  "project membership": ["project_delivers_work_item"],
+  // 0.34.0. Its own family and deliberately not merged with the nine-member
+  // `document_describes_*` set, which is not polymorphic at all: those are
+  // enumerated edges saying a document is ABOUT a thing. Transclusion says it
+  // RENDERS the thing, and the difference is the whole reason the edge exists.
+  "document transclusion": ["document_transcludes_node"]
+};
 var _POLY_KEY_SET = new Set(UPG_POLYMORPHIC_EDGE_KEYS);
 function isPolymorphicEdge(key) {
   const def = UPG_EDGE_CATALOG[key];
@@ -3875,1243 +3998,102 @@ function getEdgePropertySchema(type) {
   return def?.property_schema;
 }
 
-// src/catalog/legacy-product-stages.ts
-var LEGACY_PRODUCT_STAGES = Object.freeze({
-  idea: "concept"
-});
-function migrateProductStage(stage) {
-  if (stage === void 0 || stage === null) {
-    return void 0;
-  }
-  if (typeof stage !== "string") {
-    return stage;
-  }
-  const lower = stage.toLowerCase();
-  const mapped = LEGACY_PRODUCT_STAGES[lower];
-  return mapped ?? stage;
-}
-function isLegacyProductStage(stage) {
-  return typeof stage === "string" && stage.toLowerCase() in LEGACY_PRODUCT_STAGES;
-}
-
-// src/shapes/base-node.ts
-var BASE_NODE_FIELD_PRESENCE = {
-  id: true,
-  type: true,
-  title: true,
-  slug: true,
-  aliases: true,
-  key: true,
-  description: true,
-  tags: true,
-  status: true,
-  archived: true,
-  archived_at: true,
-  source_id: true,
-  source_type: true,
-  mapping_confidence: true,
-  external_tool: true,
-  external_ref: true,
-  external_id: true,
-  external_links: true,
-  created_at: true,
-  updated_at: true,
-  properties: true
-};
-var UPG_BASE_NODE_FIELDS = Object.freeze(
-  Object.keys(BASE_NODE_FIELD_PRESENCE)
-);
-var UPG_BASE_NODE_FIELD_SET = new Set(UPG_BASE_NODE_FIELDS);
-var UPG_BASE_NODE_SPECIAL_MERGE_FIELDS = /* @__PURE__ */ new Set([
-  "id",
-  "type",
-  "slug",
-  "aliases",
-  "properties"
-]);
-
-// src/shapes/document.ts
-var UPG_CROSS_ONLY_EDGE_TYPES = [
-  // Peer overlap: "these two products share / overlap on this thing." Symmetric,
-  // no canonical instance_of identity. shares_job / shares_need are the job/need
-  // siblings of the persona/competitor/metric peers (connective layer, 0.13.1).
-  "shares_persona",
-  "shares_competitor",
-  "shares_metric",
-  "shares_job",
-  "shares_need",
-  // Product-to-product relationships.
-  "depends_on_product",
-  // runtime dependency (built-on / dogfood), not containment
-  "cannibalises",
-  "succeeds",
-  "hosts",
-  // host runs the hosted product inside itself (container -> contained)
-  // OKR / measurement rollup primitives: the cascade ACROSS products (subordinate
-  // -> superior). `contributes_to` rolls a product strategy entity up to a higher-
-  // level one; `rolls_up_to` feeds a product metric into a higher-level north-star.
-  "contributes_to",
-  "rolls_up_to",
-  // Canonical instance + area-to-audience: the target lives in the portfolio
-  // `registry` section (`registry/{node_id}`). `instance_of` is same-type
-  // canonical-to-instance; the area edges are minted via `link_area_to_audience`.
-  "instance_of",
-  "area_serves_persona",
-  "area_targets_market_segment",
-  // Foundations (0.9.12): a product-graph entity links to a canonical specification
-  // or primitive in the registry (`registry/{node_id}` target, same shape as
-  // instance_of). Registry-internal spec-to-spec links are catalog edges, not these.
-  "product_implements_specification",
-  "product_exposes_specification",
-  "feature_conforms_to_specification",
-  "api_contract_speaks_specification",
-  "product_exposes_primitive",
-  "feature_manipulates_primitive",
-  "primitive_stored_as_data_type"
-];
-var UPG_CROSS_EDGE_TYPES = [
-  ...UPG_CROSS_ONLY_EDGE_TYPES,
-  ...UPG_CROSS_ELIGIBLE_CATALOG_EDGE_TYPES
-];
-var REGISTRY_PRODUCT_ID = "registry";
-var UPG_PORTFOLIO_KINDS = ["owned", "watched", "strategic", "internal", "gtm"];
-
-// src/registry/entity-type-resolution.ts
-var TYPES = getTypes();
-var TYPES_SET = new Set(TYPES);
-var UnknownEntityTypeError = class extends Error {
-  suggestions;
-  rawType;
-  constructor(rawType, suggestions) {
-    const suffix = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?` : "";
-    super(`Unknown entity type: "${rawType}".${suffix}`);
-    this.name = "UnknownEntityTypeError";
-    this.rawType = rawType;
-    this.suggestions = suggestions;
-  }
+// src/grammar/lifecycles.ts
+var PRODUCT_LIFECYCLE = {
+  entity_type: "product",
+  initial_phase: "concept",
+  terminal_phases: ["sunset"],
+  phases: [
+    {
+      id: "concept",
+      status_category: "triage",
+      label: "Concept",
+      description: "Napkin idea. Problem shape and solution sketch, pre-validation.",
+      transitions_to: ["validation", "build", "beta", "launch", "growth", "mature", "sunset"]
+    },
+    {
+      id: "validation",
+      status_category: "started",
+      label: "Validation",
+      description: "Testing demand. User conversations and experiments pressure-test assumptions before build commits.",
+      transitions_to: ["build", "beta", "launch", "growth", "mature", "sunset"]
+    },
+    {
+      id: "build",
+      status_category: "started",
+      label: "Build",
+      description: "Actively developing v1. Core functionality is being authored, pre-user.",
+      transitions_to: ["beta", "launch", "growth", "mature", "sunset"]
+    },
+    {
+      id: "beta",
+      status_category: "started",
+      label: "Beta",
+      description: "Early users, iterating. Feature-complete enough to learn from, still changing weekly.",
+      transitions_to: ["launch", "growth", "mature", "maintenance", "sunset"]
+    },
+    {
+      id: "launch",
+      status_category: "started",
+      label: "Launch",
+      description: "Generally available. Announced to the target audience, open past beta access.",
+      transitions_to: ["growth", "mature", "maintenance", "sunset"]
+    },
+    {
+      id: "growth",
+      status_category: "started",
+      label: "Growth",
+      description: "Scaling users and revenue. Product fit validated; focus is acquisition, retention, expansion.",
+      transitions_to: ["mature", "maintenance", "sunset"]
+    },
+    {
+      id: "mature",
+      status_category: "started",
+      label: "Mature",
+      description: "Stable. Growth levelled; investment weights toward optimisation, efficiency, and durability.",
+      transitions_to: ["maintenance", "sunset"]
+    },
+    {
+      id: "maintenance",
+      status_category: "started",
+      label: "Maintenance",
+      description: "Sustaining. Minimal investment keeps the product running for existing users. Can transition back to `mature` on a strategic revival.",
+      transitions_to: ["mature", "sunset"]
+    },
+    {
+      id: "sunset",
+      status_category: "completed",
+      label: "Sunset",
+      description: "Winding down or retired. Existing users are being migrated or offboarded.",
+      transitions_to: []
+    }
+  ]
 };
-function withinEditDistance1(a, b) {
-  if (a === b) return true;
-  const al = a.length;
-  const bl = b.length;
-  if (Math.abs(al - bl) > 1) return false;
-  let i = 0;
-  let j = 0;
-  let edits = 0;
-  while (i < al && j < bl) {
-    if (a[i] !== b[j]) {
-      if (++edits > 1) return false;
-      if (al > bl) i++;
-      else if (bl > al) j++;
-      else {
-        i++;
-        j++;
-      }
-    } else {
-      i++;
-      j++;
-    }
-  }
-  if (i < al || j < bl) edits++;
-  return edits <= 1;
-}
-function resolveEntityType(rawType) {
-  if (typeof rawType !== "string" || rawType.length === 0) {
-    throw new UnknownEntityTypeError(String(rawType ?? ""), []);
-  }
-  if (TYPES_SET.has(rawType)) {
-    return { canonical: rawType };
-  }
-  const replacement = getReplacementType(rawType);
-  if (replacement && TYPES_SET.has(replacement)) {
-    return { canonical: replacement, alias: { from: rawType, to: replacement } };
-  }
-  const suggestions = [];
-  for (const t of TYPES) {
-    if (withinEditDistance1(t, rawType)) suggestions.push(t);
-    if (suggestions.length >= 5) break;
-  }
-  throw new UnknownEntityTypeError(rawType, suggestions);
-}
-
-// src/grammar/hierarchy.ts
-var UPG_VALID_CHILDREN = {
-  // ── Foundations (0.9.12): registry canonicals that self-nest. A
-  //    specification extends a specification (a dialect of a parent spec); a
-  //    primitive composes primitives (a block contains spans). These back the
-  //    hierarchy-classified specification_extends_specification /
-  //    primitive_composes_primitive catalog edges.
-  specification: ["specification"],
-  primitive: ["primitive"],
-  // An operating_lifecycle (e.g. the content-ops lifecycle) contains its ordered
-  // operating_stage children. Backs the operating_lifecycle_contains_operating_stage edge.
-  operating_lifecycle: ["operating_stage"],
-  // ── Product (root) ─────────────────────────────────────────────────────────
-  product: [
-    // Strategy
-    "vision",
-    "outcome",
-    "objective",
-    "metric",
-    "decision",
-    "constraint",
-    // User
-    "persona",
-    // Discovery (via outcome children)
-    // Validation (via hypothesis children)
-    // Market Intelligence
-    "competitor",
-    "market_trend",
-    "market_segment",
-    "competitive_analysis",
-    // User Research
-    "research_study",
-    // Experience Design
-    "user_journey",
-    "user_flow",
-    "wireframe",
-    "screen",
-    // Design System
-    "design_system",
-    "design_component",
-    // Brand Identity
-    "brand_identity",
-    // Product Specification
-    "feature",
-    "feature_area",
-    "release",
-    "roadmap",
-    "roadmap_theme",
-    "planning_cycle",
-    // Configuration (0.30.0): the levers whose values select which surface tree
-    // the product renders. Few per product, and top-level because an axis is a
-    // product-wide fact rather than a child of any one feature or surface.
-    "configuration_axis",
-    // Classification (0.32.0): the product's own taxonomies — the grouped-label
-    // case, one named group over a set of values. Same reasoning as the
-    // configuration axis above, and until now the only parent a
-    // classification_axis could have was a competitive_analysis.
-    "classification_axis",
-    // Engineering
-    "bounded_context",
-    "code_repository",
-    "integration_pattern",
-    "external_api",
-    "data_flow",
-    // Growth
-    "funnel",
-    "acquisition_channel",
-    "cohort",
-    "behavioral_segment",
-    "growth_loop",
-    "attribution_model",
-    // Business Model
-    "business_model",
-    // Go-To-Market
-    "gtm_strategy",
-    // Team & Organisation
-    // `person` is containment-free (see UPG_CONTAINMENT_FREE_TYPES below)
-    // (referenced via edges, not nested under product)
-    "team",
-    "stakeholder",
-    "department",
-    // Data & Analytics
-    "data_source",
-    "event_schema",
-    "dashboard",
-    "data_domain",
-    "glossary_term",
-    // Content & Knowledge
-    "content_piece",
-    "knowledge_base_article",
-    "brand_asset",
-    "document",
-    "documentation_template",
-    // Legal
-    "legal_entity",
-    "privacy_policy",
-    // Compliance
-    "compliance_requirement",
-    "risk",
-    "data_contract",
-    "audit_log_policy",
-    "compliance_framework",
-    // DevOps & Platform
-    "service_level_objective",
-    "incident",
-    "runbook",
-    "monitor",
-    "ci_pipeline",
-    "release_strategy",
-    "on_call_rotation",
-    "infrastructure_component",
-    // Security
-    "threat_model",
-    "security_control",
-    "security_policy",
-    "penetration_test",
-    "security_review",
-    "data_classification",
-    "access_policy",
-    // Accessibility
-    "a11y_standard",
-    "a11y_audit",
-    "a11y_annotation",
-    // Quality Assurance
-    "test_plan",
-    "test_suite",
-    "qa_session",
-    "test_coverage_report",
-    "test_environment",
-    // Customer Feedback
-    "feedback_program",
-    "user_advisory_board",
-    "beta_program",
-    // Pricing & Packaging
-    "pricing_strategy",
-    // AI & Machine Learning
-    "ai_model",
-    "model_comparison",
-    // Workflows & Agents
-    "workflow_template",
-    "agent_definition",
-    // Sales & Revenue
-    "pipeline_sales",
-    "account",
-    "lead",
-    "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",
-    "event",
-    "community_initiative",
-    // Customer Success
-    "support_ticket",
-    "customer_feedback",
-    "churn_reason",
-    "customer_health_score",
-    "playbook",
-    "service_level_agreement",
-    "success_milestone",
-    "service_blueprint",
-    "nps_campaign",
-    // Localisation
-    "locale",
-    "locale_config",
-    // Customer Education
-    "education_program",
-    // Partners & Ecosystem
-    "partner_program",
-    "api_ecosystem",
-    "developer_portal",
-    // Portfolio
-    // (UPG-677) product no longer lists product_area as a child: the
-    // product↔product_area containment is the single direction
-    // product_area_contains_product (product_area → product). The inverse
-    // product_categorised_in_product_area edge was collapsed.
-    // Workspace
-    "workspace"
-  ],
-  // ── Metric & Outcome hierarchy ──────────────────────────────────────────────
-  outcome: ["metric", "opportunity", "feature"],
-  // ── User & Jobs hierarchy ───────────────────────────────────────────────────
-  persona: ["job", "need", "switching_cost", "desired_outcome"],
-  job: ["need", "desired_outcome", "job_step"],
-  // ── Discovery hierarchy ─────────────────────────────────────────────────────
-  opportunity: ["solution", "design_concept", "feasibility_study", "design_sprint"],
-  // solutions now propose hypothesis (the templated
-  // belief), not the legacy hypothesis type.
-  solution: ["hypothesis", "prototype", "metric"],
-  // ── Validation hierarchy ────────────────────────────────────────────────────
-  // (UPG-664) The validation chain is a single-parent line:
-  //   hypothesis ▷ experiment_plan ▷ experiment ▷ experiment_run.
-  // hypothesis is canonical (hypothesis_evidence collapsed into evidence;
-  // relationship expressed via hypothesis_has_evidence edge; evidence.direction
-  // carries supports/refutes/neutral semantics). `test_plan` re-homed to the
-  // QA/testing domain (UPG-678), so it is no longer a hypothesis child.
-  hypothesis: ["experiment_plan", "research_plan", "evidence"],
-  // experiment_plan is the canonical validation PLAN (graduated stable,
-  // UPG-664). It designs the experiment it produces; the plan owns the
-  // experiment in the containment line. It also retains experiment_run as a
-  // child for the v0.2.6 split-migration path
-  // (`experiment_plan_ran_as_experiment_run`), where a legacy experiment routes
-  // directly to a plan + run pair.
-  experiment_plan: ["experiment", "experiment_run"],
-  // experiment is the canonical structured test. It owns its run(s) and the
-  // learning/evidence it produces. The optional experiment_run child captures
-  // the multi-run / replication case.
-  experiment: ["experiment_run", "learning", "evidence"],
-  // experiment_run carries learning/evidence/metric children (run produces
-  // evidence) and self-nests for replications/multi-armed runs (V9: this is
-  // where self-nesting genuinely lives, not on `experiment`).
-  experiment_run: ["learning", "evidence", "metric", "experiment_run"],
-  // ── OKR hierarchy ──────────────────────────────────────────────────────────
-  // strategic_question (0.17.4): an open coordination question raised under an
-  // objective (objective_raises_strategic_question, hierarchy).
-  objective: ["key_result", "metric", "strategic_question"],
-  key_result: ["metric"],
-  // ── Strategic cascade: vision → mission → strategic_pillar → strategic_theme →
-  //    { initiative, objective } ───────────────────────────────────────────────
-  //
-  // strategic_pillar vs strategic_theme (UPG-692 T3.3 — distinct cascade levels,
-  // NOT duplicates; sharpened rather than merged):
-  //   - strategic_pillar = a DURABLE structural division of the strategy. A
-  //     standing area the org organises around for years (e.g. "Structured
-  //     content", "Developer experience"). Few, long-lived; time_horizon is
-  //     multi-year / open-ended; carries its own `success_indicator`.
-  //   - strategic_theme = a TIME-BOUND thrust WITHIN a pillar. The current bet
-  //     for a period (e.g. "Go AI-native this year"). More numerous, rotates;
-  //     time_horizon is bounded (Q / FY); has NO `success_indicator` because it
-  //     is measured through its child objectives (strategic_theme_contains_objective).
-  //     That success-measurement asymmetry is the load-bearing distinction.
-  vision: ["mission"],
-  mission: ["strategic_pillar"],
-  // 0.20.1: metric added as a strategic_pillar child, backing
-  // strategic_pillar_measured_by_metric (hierarchy) — the pillar's own
-  // north-star, mirrored from objective: ['key_result', 'metric', ...] one
-  // level down the cascade.
-  strategic_pillar: ["strategic_theme", "capability", "value_stream", "decision", "metric"],
-  // v0.5.4 (UPG-511): objectives are the specific quarterly bets *within* a
-  // strategic theme. The theme is the multi-quarter focus area; objectives are
-  // subordinate. Pairs with `strategic_theme_contains_objective` in the edge
-  // catalog (hierarchy, strategic_theme → objective, reverse_verb: rolls_up_to;
-  // renamed from objective_rolls_up_to_strategic_theme in UPG-676).
-  strategic_theme: ["initiative", "objective"],
-  initiative: ["assumption", "strategic_question"],
-  // v0.5.2 (UPG-528): capability decomposes into sub-capabilities (Wardley
-  // value-chain spine) and is realised by user-facing features. Pairs with
-  // `capability_depends_on_capability` and `capability_implemented_by_feature`
-  // in the edge catalogue. The self-loop guard (UPG-520) keeps A → A refused;
-  // A → B between distinct capabilities is the supported decomposition.
-  capability: ["capability", "feature"],
-  // ── Market hierarchy ────────────────────────────────────────────────────────
-  // competitive_analysis hosts classification axes (its dimensions);
-  // each axis hosts its values; values are reusable across the row and column
-  // dossiers of a 2-axis matrix.
-  competitive_analysis: ["competitor", "market_trend", "market_segment", "classification_axis"],
-  competitor: ["competitor_feature", "competitor_signal"],
-  classification_axis: ["classification_value"],
-  // ── UX Research hierarchy ───────────────────────────────────────────────────
-  research_study: [
-    "participant",
-    "observation",
-    "affinity_cluster",
-    "research_question",
-    "interview_guide",
-    "insight",
-    "survey_response"
-  ],
-  observation: ["quote"],
-  // F6 (UPG-672): affinity_cluster owns the observations it groups, in addition
-  // to the insights it synthesises. Pairs with `affinity_cluster_groups_observation`
-  // in the edge catalog (hierarchy). An observation can be both directly owned by
-  // its research_study and grouped under an affinity_cluster (multi-parent grammar).
-  affinity_cluster: ["insight", "observation"],
-  // insight refines into insight; a raw insight can be distilled
-  // into a more specific insight (refines_into chain).
-  // v0.5.8 (UPG-528 Part 2d): insights own their evidencing quotes;
-  // parallel to `observation: ['quote']`. Research-synthesis canon.
-  // Pairs with `insight_evidenced_by_quote` in the edge catalog.
-  // ── Design hierarchy ────────────────────────────────────────────────────────
-  // (UPG-663, v0.9.2) A user_journey owns its steps (the stable 0.1.0 spine)
-  // and carries phases as a non-owning band overlay. A journey_phase is NO
-  // LONGER a containment parent of journey_step: it SPANS steps via the
-  // `journey_phase_spans_journey_step` edge (mirroring the marketing
-  // `customer_journey_stage_spans_journey_step` precedent), so each step has
-  // exactly one containment parent and the journey has one canonical step list.
-  user_journey: ["journey_step", "journey_phase"],
-  journey_step: ["journey_action"],
-  // v0.5.8 (UPG-528 Part 2d): insights own their evidencing quotes;
-  // parallel to `observation: ['quote']`. Research-synthesis canon
-  // (insight ← quote evidencing) extends quote's hierarchy parents to
-  // both observation (raw-capture parent) and insight (synthesis parent).
-  // Pairs with `insight_evidenced_by_quote` in the edge catalog.
-  insight: ["design_question", "insight", "quote"],
-  // v0.5.2 (UPG-528): need anchors a Wardley value chain; capabilities
-  // fulfil the need at the chain top. Cross-domain hierarchy (need ∈ Design,
-  // capability ∈ Strategy) is intentional: Wardley analysis starts from a
-  // user need and decomposes into the capabilities required to fulfil it.
-  need: ["design_question", "capability"],
-  design_question: ["design_concept"],
-  design_concept: ["prototype", "wireframe"],
-  design_component: [
-    "design_token",
-    "design_pattern",
-    "design_guideline",
-    "interaction_spec",
-    "design_component"
-  ],
-  // self-nesting for atomic hierarchy (organism → molecule → atom)
-  prototype: ["annotation"],
-  // ── Brand hierarchy ─────────────────────────────────────────────────────────
-  brand_identity: [
-    "brand_colour",
-    "brand_typography",
-    "brand_asset",
-    "brand_voice",
-    "brand_logo",
-    "brand_imagery"
-  ],
-  // ── Product Specification hierarchy ─────────────────────────────────────────
-  // story_task collapsed into canonical task. feature now owns
-  // task directly; story-derived tasks implement user_story via
-  // task_implements_user_story edge.
-  feature: ["epic", "bug", "task"],
-  feature_area: ["feature", "feature_area"],
-  // epic owns user_story (the templated promise) and, mirroring feature, may
-  // also directly contain bug/task — heterogeneous imported tickets that belong
-  // to one epic rather than the feature as a whole (feedback df99026a).
-  epic: ["user_story", "bug", "task"],
-  user_story: ["acceptance_criterion"],
-  task: ["task"],
-  // planning_cycle (0.20.0): the cadence axis self-nests (a program-increment
-  // contains iterations; a cycle contains its cooldown) via
-  // planning_cycle_contains_planning_cycle. It does NOT contain user_story as a
-  // child: scheduling work into a cycle is the semantic, deliberate-only
-  // planning_cycle_schedules_work_item edge, so the item keeps its feature/epic
-  // containment parent and is merely referenced by the cycle.
-  planning_cycle: ["planning_cycle"],
-  // ── Engineering hierarchy ───────────────────────────────────────────────────
-  bounded_context: [
-    "service",
-    "domain_event",
-    "decision",
-    "data_model",
-    "aggregate",
-    "read_model",
-    "code_repository",
-    "integration_pattern",
-    "external_api",
-    "data_flow",
-    // v0.5.7 (UPG-528 Part 2c): BCs publish api_contracts as their "published
-    // language" (DDD canon). api_contract has two valid hierarchy parents now:
-    // service (per-service exposure) AND bounded_context (BC-level surface).
-    "api_contract"
-  ],
-  service: [
-    "api_contract",
-    "technical_debt_item",
-    "feature_flag",
-    "deployment",
-    "api_endpoint",
-    "database_schema",
-    "queue_topic",
-    "build_artifact",
-    "library_dependency"
-  ],
-  // v0.5.1 (UPG-517 C2): contracts contain their endpoints. Service still
-  // serves endpoints directly (legacy / non-contract endpoints); both
-  // parent-child paths coexist.
-  api_contract: ["api_endpoint"],
-  decision: ["technical_debt_item"],
-  aggregate: ["domain_entity", "value_object", "command"],
-  // ── Growth hierarchy ────────────────────────────────────────────────────────
-  funnel: ["funnel_step"],
-  acquisition_channel: ["growth_campaign"],
-  growth_campaign: ["experiment_plan", "variant"],
-  // ── Business Model hierarchy ─────────────────────────────────────────────────
-  business_model: [
-    "value_proposition",
-    "revenue_stream",
-    "cost_structure",
-    "unit_economics",
-    "partnership",
-    "key_resource",
-    "key_activity",
-    "customer_relationship",
-    "distribution_channel"
-  ],
-  revenue_stream: ["pricing_tier"],
-  // ── Go-To-Market hierarchy ───────────────────────────────────────────────────
-  gtm_strategy: [
-    "ideal_customer_profile",
-    "positioning",
-    "launch",
-    "content_strategy",
-    "sales_motion",
-    "competitive_battle_card",
-    "demand_gen_program",
-    "territory"
-  ],
-  positioning: ["messaging", "objection", "proof_point"],
-  value_proposition: ["objection", "proof_point"],
-  competitive_battle_card: ["objection"],
-  objection: ["rebuttal"],
-  rebuttal: ["proof_point"],
-  // ── Team & Organisation hierarchy ───────────────────────────────────────────
-  department: ["team", "stakeholder"],
-  team: [
-    "role",
-    "team_okr",
-    "retrospective",
-    "dependency",
-    "skill",
-    "ceremony",
-    "capacity_plan",
-    "decision",
-    // Self-nesting (0.17.2): a parent team contains its sub-teams / squads, one
-    // level below department_contains_team. Backs team_contains_team. Mirrors
-    // feature_area_contains_feature_area (same-type child listed last).
-    "team"
-  ],
-  // ── Data & Analytics hierarchy ───────────────────────────────────────────────
-  data_source: ["metric", "data_pipeline", "data_lineage", "event_schema"],
-  // UPG-685 T0.4 (0.13.0 Wave 1): `outcome` removed as a metric child. It closed a
-  // containment cycle (outcome ⊃ metric ⊃ outcome) and was backed only by the CAUSAL
-  // `metric_drives_outcome` edge, not a hierarchy edge — the "metric leads to outcome"
-  // meaning lives correctly on that causal edge. The real containment (outcome ⊃ metric)
-  // is kept. Sub-metric trees (metric ⊃ metric) stay.
-  metric: ["metric", "data_quality_rule", "metric_quality_assessment"],
-  data_domain: ["data_product", "data_source", "glossary_term", "data_model", "dashboard"],
-  dashboard: ["report", "experiment_run"],
-  // ── Content & Knowledge hierarchy ────────────────────────────────────────────
-  // release contains features and bugs (GitHub milestone→issue import).
-  release: ["changelog", "feature", "bug"],
-  content_strategy: ["content_calendar", "content_theme"],
-  content_calendar: [
-    "content_theme",
-    "content_piece",
-    "knowledge_base_article",
-    "brand_asset",
-    "document",
-    "documentation_template"
-  ],
-  // ── Operations & CS hierarchy ────────────────────────────────────────────────
-  service_blueprint: [
-    "user_flow",
-    "playbook",
-    "service_level_agreement",
-    "customer_health_score",
-    "support_ticket",
-    "customer_feedback"
-  ],
-  customer_health_score: ["nps_campaign", "success_milestone"],
-  customer_feedback: ["churn_reason"],
-  user_flow: ["screen", "customer_journey_stage"],
-  customer_journey_stage: ["touchpoint"],
-  // ── Legal, Compliance & Risk hierarchy ──────────────────────────────────────
-  legal_entity: ["ip_asset", "contract"],
-  contract: ["contract_clause"],
-  compliance_framework: [
-    "security_audit",
-    "compliance_requirement",
-    "privacy_policy",
-    "audit_log_policy",
-    "risk",
-    "data_contract",
-    "legal_entity"
-  ],
-  // ── DevOps & Platform hierarchy ──────────────────────────────────────────────
-  infrastructure_component: [
-    "service_level_objective",
-    "monitor",
-    "ci_pipeline",
-    "incident",
-    "runbook",
-    "release_strategy",
-    "on_call_rotation"
-  ],
-  service_level_objective: ["service_level_indicator", "error_budget"],
-  incident: ["postmortem"],
-  monitor: ["alert_rule"],
-  ci_pipeline: ["build_artifact"],
-  // ── Security hierarchy ───────────────────────────────────────────────────────
-  security_policy: [
-    "security_control",
-    "access_policy",
-    "data_classification",
-    "threat_model",
-    "security_review",
-    "incident"
-  ],
-  security_review: ["penetration_test"],
-  threat_model: ["threat", "vulnerability"],
-  // ── Sales & Revenue hierarchy ────────────────────────────────────────────────
-  pipeline_sales: ["pipeline_stage", "lead", "account", "forecast", "subscription"],
-  account: ["contact", "deal"],
-  deal: ["quote_document"],
-  subscription: ["invoice"],
-  // ── Program Management hierarchy ─────────────────────────────────────────────
-  program: ["project", "risk_register", "change_request", "resource_allocation", "status_report"],
-  project: ["milestone", "deliverable"],
-  risk_register: ["risk"],
-  // ── Accessibility hierarchy ──────────────────────────────────────────────────
-  a11y_standard: ["a11y_guideline", "a11y_audit", "a11y_annotation"],
-  a11y_audit: ["a11y_issue"],
-  // ── Product Specification expansion ─────────────────────────────────────────
-  roadmap: ["roadmap_item", "roadmap_theme", "release"],
-  roadmap_theme: ["feature"],
-  // ── Unified Context Layer hierarchy ─────────────────────────────────────────
-  design_system: [
-    "design_component",
-    "design_token",
-    "design_guideline",
-    "brand_identity",
-    "user_journey",
-    "user_flow",
-    "insight"
-  ],
-  screen: ["screen_state", "screen", "surface", "design_component", "wireframe"],
-  // self-nesting + surfaces + components + wireframes
-  // surface (0.27.0): the place inside a screen. Self-nests, so a shell holds
-  // panes, a pane holds regions, a region holds slots. A surface is reached
-  // through the screen that renders it (`screen: [... 'surface']`), never as a
-  // top-level product child: every UPG_VALID_CHILDREN pair must be backed by a
-  // hierarchy-classified edge (guardrail G2b), and the ratified ten do not
-  // include a product-to-surface verb. An app-shell surface therefore hangs off
-  // the screen that mounts it.
-  //
-  // NOTE: `surface_kind` narrows this further than UPG_VALID_CHILDREN can
-  // express. UPG_VALID_CHILDREN is keyed on entity TYPE, so it can only say
-  // "a surface may contain a surface"; the kind ordering (shell > tool > pane >
-  // region > slot / gutter / action_bar, with overlay and ambient parented by
-  // whatever raises them) is a property-level rule documented on `SurfaceKind`
-  // and enforced by validators, not by this table. Precedent: the same split
-  // applies to `planning_cycle`, whose `cadence_kind` narrows its self-nesting.
-  surface: ["surface", "design_component"],
-  // ── Marketing & Communications hierarchy ────────────────────────────────────
-  marketing_strategy: [
-    "marketing_channel",
-    "seo_keyword",
-    "press_release",
-    "event",
-    "community_initiative"
-  ],
-  marketing_channel: ["marketing_campaign_plan"],
-  marketing_campaign_plan: ["email_sequence", "social_post", "ad_creative"],
-  // ── Localisation & i18n hierarchy ───────────────────────────────────────────
-  locale: ["translation_bundle", "cultural_adaptation", "regional_pricing", "locale_config"],
-  translation_bundle: ["translation_key"],
-  // ── Customer Education & Training hierarchy ──────────────────────────────────
-  education_program: [
-    "tutorial",
-    "walkthrough",
-    "webinar",
-    "certification",
-    "help_video",
-    "learning_path"
-  ],
-  // a learning_path can include its terminal certification.
-  learning_path: ["tutorial", "certification"],
-  // ── Quality Assurance & Testing hierarchy ────────────────────────────────────
-  // (UPG-678) test_plan re-homed validation → QA. It is the QA planning layer:
-  // the verification approach (scope, environments, pass criteria) that the
-  // test suites execute. A test_plan groups the suites that carry it out.
-  test_plan: ["test_suite", "test_environment"],
-  test_suite: [
-    "test_case",
-    "regression_test",
-    "qa_session",
-    "test_coverage_report",
-    "test_environment",
-    "test_result"
-  ],
-  test_case: ["test_result"],
-  qa_session: ["bug"],
-  // ── Partner & Ecosystem Management hierarchy ─────────────────────────────────
-  partner_program: [
-    "partner_tier",
-    "integration_partner",
-    "partner_revenue_share",
-    "api_ecosystem",
-    "developer_portal"
-  ],
-  api_ecosystem: ["marketplace_listing"],
-  // ── Feedback & Voice of Customer hierarchy ───────────────────────────────────
-  feedback_program: [
-    "feature_request",
-    "nps_campaign",
-    "feedback_theme",
-    "user_advisory_board",
-    "beta_program"
-  ],
-  feature_request: ["feedback_vote"],
-  // v0.5.8 (UPG-528 Part 2d): CABs convene as quarterly ceremonies;
-  // CAB owns its meeting cadence (Stettler, Moore CAB playbook canon).
-  // Pairs with `user_advisory_board_convenes_as_ceremony` in the edge
-  // catalog. ceremony now has two valid hierarchy parents (team for sprint
-  // ceremonies, user_advisory_board for CAB meetings).
-  user_advisory_board: ["ceremony"],
-  // ── Pricing & Packaging hierarchy ────────────────────────────────────────────
-  pricing_strategy: [
-    "experiment_plan",
-    "pricing_tier",
-    "discount_strategy",
-    "trial_config",
-    "paywall"
-  ],
-  // ── AI/ML Operations hierarchy ───────────────────────────────────────────────
-  // (UPG-665) The prompt abstraction is corrected: ai_model → prompt_template →
-  // prompt_version (a model has templates; each template has versions). The
-  // model no longer owns prompt_version directly.
-  ai_model: [
-    "prompt_template",
-    "eval_benchmark",
-    "ai_cost_tracker",
-    "hallucination_report",
-    "ai_guardrail",
-    "model_comparison",
-    "ai_experiment",
-    "ai_dataset",
-    "ai_trace"
-  ],
-  // prompt_template owns its prompt_versions the way a file owns its commits.
-  prompt_template: ["prompt_version"],
-  // v0.5.7 (UPG-528 Part 2c): benchmarks define the metric set they measure
-  // (HELM, MLPerf, BIG-bench all spec a metric list). metric already has many
-  // hierarchy parents (outcome, objective, key_result, solution, data_source).
-  eval_benchmark: ["eval_run", "metric"],
-  // ai_trace spawns child traces for sub-calls (tool calls, chained
-  // prompts). Self-nesting enables call-tree representation.
-  ai_trace: ["ai_trace"],
-  // ── Agentic Workflows & Process hierarchy ────────────────────────────────────
-  workflow_template: ["workflow_run", "review_gate", "agent_task"],
-  workflow_run: ["workflow_artifact"],
-  agent_definition: ["agent_session", "agent_skill", "agent_hook", "workflow_template", "agent_task"],
-  // v0.5.8 (UPG-528 Part 2d): review gates also vet research insights
-  // (ResearchOps insight-review pattern). Pairs with `review_gate_vets_insight`
-  // in the edge catalog. The gate now owns two child types: approval records
-  // for workflow gates, insights for research-democratisation gates.
-  review_gate: ["approval_record", "insight"],
-  // ── Investigation hierarchy ──────────────────────────────────────────────────
-  investigation: ["symptom", "root_cause"],
-  root_cause: ["fix"],
-  // ── Portfolio layer hierarchy ────────────────────────────────────────────────
-  // organization → product_area is the org-axis anchor (who owns what);
-  // organization → portfolio is the strategic-axis anchor (where you invest).
-  // organization → workspace (WS3, 2026-07-05): org-altitude workspace anchor
-  // (organization_thinks_in_workspace) — a workspace scoped to org altitude
-  // lives in the same portfolio-level graph as its organization node.
-  organization: ["portfolio", "product_area", "workspace"],
-  // portfolios can nest (multi-level investment structures).
-  portfolio: ["product", "portfolio"],
-  // product_area is the organisational container for products and can
-  // nest (parent → sub-area). product_area also groups features; the
-  // "Studio area owns 6 features" mental model. product_area → workspace
-  // (WS3, 2026-07-05): plane-altitude workspace anchor
-  // (product_area_thinks_in_workspace) — "plane" is Entopo's app-level name
-  // for product_area, not a distinct spec entity.
-  product_area: ["product", "product_area", "feature", "workspace"]
-};
-function getValidChildren(entityType) {
-  return UPG_VALID_CHILDREN[entityType] ?? [];
-}
-function canBeChildOf(childType, parentType) {
-  return getValidChildren(parentType).includes(childType);
-}
-var UPG_CONTAINMENT_FREE_TYPES = /* @__PURE__ */ new Set([
-  "person",
-  // A framework_exercise has no structural parent: it anchors to the entities
-  // it scores via the `framework_exercise_includes_node` edge, not by
-  // 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",
-  // 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",
-  // A capture has no structural parent for the same reason: it anchors to what
-  // it RENDERS, via `capture_renders_node`. Giving it a product parent would
-  // claim a capture is part of the product rather than a picture of one, and
-  // would mint a containment edge whose only job is to satisfy the hierarchy.
-  "capture"
-]);
-function isContainmentFreeType(entityType) {
-  return UPG_CONTAINMENT_FREE_TYPES.has(entityType);
-}
-
-// src/grammar/projection.ts
-var VARIES_BY_EDGE = "surface_varies_by_configuration_axis";
-var PRESENT_UNDER_PROPERTY = "present_under";
-var ACTIVE_WHEN_PROPERTY = "active_when";
-var QUALIFIABLE_EDGE_TYPES = [
-  "surface_contains_surface",
-  "feature_occupies_surface"
-];
-function readStringArray(properties, key) {
-  const raw = properties?.[key];
-  if (!Array.isArray(raw)) return void 0;
-  return raw.filter((v) => typeof v === "string");
-}
-function readActiveWhen(edge) {
-  const raw = edge.properties?.[ACTIVE_WHEN_PROPERTY];
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
-  const axis = raw.axis;
-  const values = readStringArray(raw, "values");
-  if (typeof axis !== "string" || axis.length === 0 || !values || values.length === 0) {
-    return void 0;
-  }
-  return { axis, values };
-}
-function projectGraph(nodes, edges, configuration) {
-  const axes = Object.keys(configuration);
-  if (axes.length === 0) {
-    return {
-      nodes: [...nodes],
-      edges: [...edges],
-      excluded_node_ids: [],
-      deactivated_edge_count: 0,
-      dangling_edge_count: 0
-    };
-  }
-  const excluded = /* @__PURE__ */ new Set();
-  for (const edge of edges) {
-    if (edge.type !== VARIES_BY_EDGE) continue;
-    const chosen = configuration[edge.target];
-    if (chosen === void 0) continue;
-    const presentUnder = readStringArray(edge.properties, PRESENT_UNDER_PROPERTY);
-    if (!presentUnder) continue;
-    if (!presentUnder.includes(chosen)) excluded.add(edge.source);
-  }
-  const survivingNodes = excluded.size === 0 ? [...nodes] : nodes.filter((n) => !excluded.has(n.id));
-  let deactivated = 0;
-  let dangling = 0;
-  const survivingEdges = [];
-  for (const edge of edges) {
-    const qualifier = readActiveWhen(edge);
-    if (qualifier) {
-      const chosen = configuration[qualifier.axis];
-      if (chosen !== void 0 && !qualifier.values.includes(chosen)) {
-        deactivated++;
-        continue;
-      }
-    }
-    if (excluded.has(edge.source) || excluded.has(edge.target)) {
-      dangling++;
-      continue;
-    }
-    survivingEdges.push(edge);
-  }
-  return {
-    nodes: survivingNodes,
-    edges: survivingEdges,
-    excluded_node_ids: [...excluded].sort(),
-    deactivated_edge_count: deactivated,
-    dangling_edge_count: dangling
-  };
-}
-function enumerateProjections(nodes) {
-  const out = [
-    { configuration: {} }
-  ];
-  for (const node of nodes) {
-    if (node.type !== "configuration_axis") continue;
-    const values = readStringArray(node.properties, "values");
-    if (!values) continue;
-    for (const value of values) {
-      out.push({ axis: node.id, value, configuration: { [node.id]: value } });
-    }
-  }
-  return out;
-}
-
-// src/grammar/configuration-drift.ts
-var ALTERNATES_EDGE = "surface_alternates_with_surface";
-var PARENT_EDGE_TYPES = /* @__PURE__ */ new Set(["surface_contains_surface", "screen_renders_surface"]);
-function edgeLabel(edge) {
-  return edge.id ?? `${edge.source} -> ${edge.target}`;
-}
-function checkConfigurationDrift(nodes, edges) {
-  const findings = [];
-  const axisValues = /* @__PURE__ */ new Map();
-  for (const node of nodes) {
-    if (node.type !== "configuration_axis") continue;
-    const values = readStringArray(node.properties, "values");
-    if (!values || values.length === 0) {
-      findings.push({
-        kind: "axis_values_empty",
-        severity: "error",
-        node_id: node.id,
-        axis_id: node.id,
-        message: "Configuration axis declares no values. An axis with no values selects nothing, so no projection can be taken along it."
-      });
-      axisValues.set(node.id, []);
-      continue;
-    }
-    axisValues.set(node.id, values);
-    const rawDefault = node.properties?.default_value;
-    if (typeof rawDefault === "string" && rawDefault.length > 0 && !values.includes(rawDefault)) {
-      findings.push({
-        kind: "axis_default_not_a_value",
-        severity: "error",
-        node_id: node.id,
-        axis_id: node.id,
-        message: `default_value "${rawDefault}" is not one of the axis values [${values.join(", ")}]. It names a value of this axis, so it has to be one the axis declares.`
-      });
-    }
-  }
-  for (const edge of edges) {
-    if (edge.type !== VARIES_BY_EDGE) continue;
-    const values = axisValues.get(edge.target);
-    const presentUnder = readStringArray(edge.properties, PRESENT_UNDER_PROPERTY);
-    if (!presentUnder || presentUnder.length === 0) {
-      findings.push({
-        kind: "present_under_empty",
-        severity: "error",
-        edge_id: edge.id,
-        node_id: edge.source,
-        axis_id: edge.target,
-        message: `${edgeLabel(edge)} declares variance without a non-empty present_under. A surface that exists under no configuration should be deleted rather than declared; a surface that exists under all of them should carry no varies_by edge at all.`
-      });
-      continue;
-    }
-    if (!values) continue;
-    for (const value of presentUnder) {
-      if (!values.includes(value)) {
-        findings.push({
-          kind: "present_under_unknown_value",
-          severity: "error",
-          edge_id: edge.id,
-          node_id: edge.source,
-          axis_id: edge.target,
-          message: `present_under names "${value}", which the axis does not declare. Its values are [${values.join(", ")}].`
-        });
-      }
-    }
-  }
-  for (const edge of edges) {
-    const hasQualifierKey = edge.properties !== void 0 && Object.prototype.hasOwnProperty.call(edge.properties, ACTIVE_WHEN_PROPERTY);
-    if (!hasQualifierKey) continue;
-    if (edge.type !== void 0 && !QUALIFIABLE_EDGE_TYPES.includes(edge.type)) {
-      findings.push({
-        kind: "qualifier_on_illegal_edge",
-        severity: "error",
-        edge_id: edge.id,
-        message: `active_when is not legal on ${edge.type}. The qualifier is scoped to [${QUALIFIABLE_EDGE_TYPES.join(", ")}] deliberately: conditional composition is the question this release answers, and a general modality system is not.`
-      });
-      continue;
-    }
-    const qualifier = readActiveWhen(edge);
-    if (!qualifier) {
-      const rawQualifier = edge.properties?.[ACTIVE_WHEN_PROPERTY];
-      const rawValues = rawQualifier && typeof rawQualifier === "object" && !Array.isArray(rawQualifier) ? rawQualifier.values : void 0;
-      if (Array.isArray(rawValues) && rawValues.length === 0) {
-        findings.push({
-          kind: "qualifier_values_empty",
-          severity: "error",
-          edge_id: edge.id,
-          message: `${edgeLabel(edge)} carries an active_when with an empty values list. Read literally that would remove the relationship from every configuration, which is a way to delete an edge by writing a property; it is treated as absent instead. To say a relationship never holds, delete the edge.`
-        });
-        continue;
-      }
-      findings.push({
-        kind: "qualifier_axis_unresolved",
-        severity: "error",
-        edge_id: edge.id,
-        message: `${edgeLabel(edge)} carries a malformed active_when. It must be an object with an axis id and a non-empty values array; anything else reads as absent, which silently makes the relationship invariant.`
-      });
-      continue;
-    }
-    const values = axisValues.get(qualifier.axis);
-    if (!values) {
-      findings.push({
-        kind: "qualifier_axis_unresolved",
-        severity: "error",
-        edge_id: edge.id,
-        axis_id: qualifier.axis,
-        message: `active_when names axis "${qualifier.axis}", which is not a configuration_axis node in this graph.`
-      });
-      continue;
-    }
-    for (const value of qualifier.values) {
-      if (!values.includes(value)) {
-        findings.push({
-          kind: "qualifier_unknown_value",
-          severity: "error",
-          edge_id: edge.id,
-          axis_id: qualifier.axis,
-          message: `active_when names value "${value}", which axis "${qualifier.axis}" does not declare. Its values are [${values.join(", ")}].`
-        });
-      }
-    }
-  }
-  const varianceBySource = /* @__PURE__ */ new Map();
-  for (const edge of edges) {
-    if (edge.type !== VARIES_BY_EDGE) continue;
-    const values = readStringArray(edge.properties, PRESENT_UNDER_PROPERTY) ?? [];
-    const list = varianceBySource.get(edge.source) ?? [];
-    list.push({ axis: edge.target, values });
-    varianceBySource.set(edge.source, list);
-  }
-  for (const edge of edges) {
-    if (edge.type !== ALTERNATES_EDGE) continue;
-    const left = varianceBySource.get(edge.source) ?? [];
-    const right = varianceBySource.get(edge.target) ?? [];
-    if (left.length === 0 || right.length === 0) {
-      findings.push({
-        kind: "alternation_axis_mismatch",
-        severity: "error",
-        edge_id: edge.id,
-        message: `${edgeLabel(edge)} declares an alternation, but at least one endpoint declares no variance at all. Two surfaces that are both always present are not alternatives; they co-exist.`
-      });
-      continue;
-    }
-    const sharedAxes = left.filter((l) => right.some((r) => r.axis === l.axis)).map((l) => l.axis);
-    if (sharedAxes.length === 0) {
-      findings.push({
-        kind: "alternation_axis_mismatch",
-        severity: "error",
-        edge_id: edge.id,
-        message: `${edgeLabel(edge)} declares an alternation between surfaces that vary on different axes. Alternatives are selected by ONE lever; surfaces on different levers can both be present at once.`
-      });
-      continue;
-    }
-    for (const axis of sharedAxes) {
-      const leftValues = left.find((l) => l.axis === axis)?.values ?? [];
-      const rightValues = right.find((r) => r.axis === axis)?.values ?? [];
-      const overlap = leftValues.filter((v) => rightValues.includes(v));
-      if (overlap.length > 0) {
-        findings.push({
-          kind: "alternation_overlap",
-          severity: "error",
-          edge_id: edge.id,
-          axis_id: axis,
-          message: `${edgeLabel(edge)} declares an alternation, but both surfaces are present under [${overlap.join(", ")}] on axis "${axis}". They co-exist there, so the graph is asserting "one of these" and "both, together" about the same pair.`
-        });
-      }
-    }
-  }
-  const parentsByChild = /* @__PURE__ */ new Map();
-  for (const edge of edges) {
-    if (edge.type && PARENT_EDGE_TYPES.has(edge.type)) {
-      parentsByChild.set(edge.target, (parentsByChild.get(edge.target) ?? 0) + 1);
-    }
-  }
-  for (const [axisId, values] of axisValues) {
-    for (const value of values) {
-      const projected = projectGraph(nodes, edges, { [axisId]: value });
-      const survivingParents = /* @__PURE__ */ new Map();
-      for (const edge of projected.edges) {
-        if (edge.type && PARENT_EDGE_TYPES.has(edge.type)) {
-          survivingParents.set(edge.target, (survivingParents.get(edge.target) ?? 0) + 1);
-        }
-      }
-      for (const node of projected.nodes) {
-        if (node.type !== "surface") continue;
-        if ((parentsByChild.get(node.id) ?? 0) === 0) continue;
-        if ((survivingParents.get(node.id) ?? 0) > 0) continue;
-        findings.push({
-          kind: "orphaned_under_projection",
-          severity: "warning",
-          node_id: node.id,
-          axis_id: axisId,
-          message: `Surface is present under ${axisId} = "${value}" but every containment parent it has is absent there. Either it needs a parent in that configuration, or it should declare that it is absent from it too.`
-        });
-      }
-    }
-  }
-  return findings;
-}
-
-// src/grammar/lifecycles.ts
-var PRODUCT_LIFECYCLE = {
-  entity_type: "product",
-  initial_phase: "concept",
-  terminal_phases: ["sunset"],
-  phases: [
-    {
-      id: "concept",
-      status_category: "triage",
-      label: "Concept",
-      description: "Napkin idea. Problem shape and solution sketch, pre-validation.",
-      transitions_to: ["validation", "build", "beta", "launch", "growth", "mature", "sunset"]
-    },
-    {
-      id: "validation",
-      status_category: "started",
-      label: "Validation",
-      description: "Testing demand. User conversations and experiments pressure-test assumptions before build commits.",
-      transitions_to: ["build", "beta", "launch", "growth", "mature", "sunset"]
-    },
-    {
-      id: "build",
-      status_category: "started",
-      label: "Build",
-      description: "Actively developing v1. Core functionality is being authored, pre-user.",
-      transitions_to: ["beta", "launch", "growth", "mature", "sunset"]
-    },
-    {
-      id: "beta",
-      status_category: "started",
-      label: "Beta",
-      description: "Early users, iterating. Feature-complete enough to learn from, still changing weekly.",
-      transitions_to: ["launch", "growth", "mature", "maintenance", "sunset"]
-    },
-    {
-      id: "launch",
-      status_category: "started",
-      label: "Launch",
-      description: "Generally available. Announced to the target audience, open past beta access.",
-      transitions_to: ["growth", "mature", "maintenance", "sunset"]
-    },
-    {
-      id: "growth",
-      status_category: "started",
-      label: "Growth",
-      description: "Scaling users and revenue. Product fit validated; focus is acquisition, retention, expansion.",
-      transitions_to: ["mature", "maintenance", "sunset"]
-    },
-    {
-      id: "mature",
-      status_category: "started",
-      label: "Mature",
-      description: "Stable. Growth levelled; investment weights toward optimisation, efficiency, and durability.",
-      transitions_to: ["maintenance", "sunset"]
-    },
-    {
-      id: "maintenance",
-      status_category: "started",
-      label: "Maintenance",
-      description: "Sustaining. Minimal investment keeps the product running for existing users. Can transition back to `mature` on a strategic revival.",
-      transitions_to: ["mature", "sunset"]
-    },
-    {
-      id: "sunset",
-      status_category: "completed",
-      label: "Sunset",
-      description: "Winding down or retired. Existing users are being migrated or offboarded.",
-      transitions_to: []
-    }
-  ]
-};
-var NEED_LIFECYCLE = {
-  entity_type: "need",
-  initial_phase: "raw",
-  terminal_phases: ["prioritized"],
-  phases: [
-    {
-      id: "raw",
-      status_category: "triage",
-      label: "Raw",
-      description: "Captured from an interview, observation, or support ticket. Articulation may be rough; may duplicate an existing need.",
-      transitions_to: ["validated"]
-    },
-    {
-      id: "validated",
-      status_category: "started",
-      label: "Validated",
-      description: "Corroborated by multiple data points or targeted research. The team agrees it is a real, recurring need.",
-      transitions_to: ["prioritized"]
-    },
-    {
-      id: "prioritized",
-      status_category: "completed",
-      label: "Prioritized",
-      description: "Ranked against other needs. Ready to inform opportunity definition and solution exploration.",
-      transitions_to: []
+var NEED_LIFECYCLE = {
+  entity_type: "need",
+  initial_phase: "raw",
+  terminal_phases: ["prioritized"],
+  phases: [
+    {
+      id: "raw",
+      status_category: "triage",
+      label: "Raw",
+      description: "Captured from an interview, observation, or support ticket. Articulation may be rough; may duplicate an existing need.",
+      transitions_to: ["validated"]
+    },
+    {
+      id: "validated",
+      status_category: "started",
+      label: "Validated",
+      description: "Corroborated by multiple data points or targeted research. The team agrees it is a real, recurring need.",
+      transitions_to: ["prioritized"]
+    },
+    {
+      id: "prioritized",
+      status_category: "completed",
+      label: "Prioritized",
+      description: "Ranked against other needs. Ready to inform opportunity definition and solution exploration.",
+      transitions_to: []
     }
   ]
 };
@@ -7181,367 +6163,1528 @@ var SPECIFICATION_LIFECYCLE = {
       description: "Replaced by a newer specification. Retained for historical reference.",
       transitions_to: []
     }
-  ]
-};
-var PLANNING_CYCLE_LIFECYCLE = {
-  entity_type: "planning_cycle",
-  initial_phase: "planned",
-  terminal_phases: ["closed"],
-  phases: [
-    { id: "planned", status_category: "unstarted", label: "Planned", description: "The cycle is being shaped: dates set, goal written, work scheduled into it. It has not started yet.", transitions_to: ["active"] },
-    { id: "active", status_category: "started", label: "Active", description: "The team is inside the interval; work is flowing through it.", transitions_to: ["closed"] },
-    { id: "closed", status_category: "completed", label: "Closed", description: "The interval has ended. Scheduled work has shipped, carried over, or been dropped. May reopen if the team extends or reruns it.", transitions_to: ["active"] }
-  ]
+  ]
+};
+var PLANNING_CYCLE_LIFECYCLE = {
+  entity_type: "planning_cycle",
+  initial_phase: "planned",
+  terminal_phases: ["closed"],
+  phases: [
+    { id: "planned", status_category: "unstarted", label: "Planned", description: "The cycle is being shaped: dates set, goal written, work scheduled into it. It has not started yet.", transitions_to: ["active"] },
+    { id: "active", status_category: "started", label: "Active", description: "The team is inside the interval; work is flowing through it.", transitions_to: ["closed"] },
+    { id: "closed", status_category: "completed", label: "Closed", description: "The interval has ended. Scheduled work has shipped, carried over, or been dropped. May reopen if the team extends or reruns it.", transitions_to: ["active"] }
+  ]
+};
+var UPG_LIFECYCLES = [
+  // Product (root)
+  PRODUCT_LIFECYCLE,
+  // Foundations (0.9.12)
+  SPECIFICATION_LIFECYCLE,
+  // Discovery & Validation
+  NEED_LIFECYCLE,
+  OPPORTUNITY_LIFECYCLE,
+  SOLUTION_LIFECYCLE,
+  EXPERIMENT_PLAN_LIFECYCLE,
+  RESEARCH_PLAN_LIFECYCLE,
+  FEEDBACK_PROGRAM_LIFECYCLE,
+  FEATURE_REQUEST_LIFECYCLE,
+  BETA_PROGRAM_LIFECYCLE,
+  USER_ADVISORY_BOARD_LIFECYCLE,
+  // Strategy & Product Specification
+  OUTCOME_LIFECYCLE,
+  VISION_LIFECYCLE,
+  MISSION_LIFECYCLE,
+  CAPABILITY_LIFECYCLE,
+  OBJECTIVE_LIFECYCLE,
+  KEY_RESULT_LIFECYCLE,
+  STRATEGIC_THEME_LIFECYCLE,
+  INITIATIVE_LIFECYCLE,
+  STRATEGIC_PILLAR_LIFECYCLE,
+  STRATEGIC_QUESTION_LIFECYCLE,
+  FEATURE_AREA_LIFECYCLE,
+  FEATURE_LIFECYCLE,
+  // user_story is lifecycle-free (declared in UPG_LIFECYCLE_FREE_TYPES below).
+  // story_task lifecycle removed v0.4.0; collapsed into task. task + epic are
+  // now WORK_ITEM-template-derived (UPG-690, 0.21.0) — see TEMPLATE_LIFECYCLES.
+  RELEASE_LIFECYCLE,
+  ROADMAP_ITEM_LIFECYCLE,
+  PLANNING_CYCLE_LIFECYCLE,
+  IP_ASSET_LIFECYCLE,
+  CONTRACT_LIFECYCLE,
+  DESIGN_CONCEPT_LIFECYCLE,
+  BRAND_IDENTITY_LIFECYCLE,
+  SCREEN_LIFECYCLE,
+  SURFACE_LIFECYCLE,
+  // Engineering & Operations
+  SERVICE_LIFECYCLE,
+  DEPLOYMENT_LIFECYCLE,
+  FEATURE_FLAG_LIFECYCLE,
+  INVESTIGATION_LIFECYCLE,
+  EXTERNAL_API_LIFECYCLE,
+  DATABASE_SCHEMA_LIFECYCLE,
+  INCIDENT_LIFECYCLE,
+  SECURITY_CONTROL_LIFECYCLE,
+  DATA_PIPELINE_LIFECYCLE,
+  AI_MODEL_LIFECYCLE,
+  WORKFLOW_RUN_LIFECYCLE,
+  AGENT_DEFINITION_LIFECYCLE,
+  AGENT_SESSION_LIFECYCLE,
+  REVIEW_GATE_LIFECYCLE,
+  TEST_SUITE_LIFECYCLE,
+  TEST_CASE_LIFECYCLE,
+  // ── Phase B hand-authored ─────────────────────────────────────────
+  // Research + Validation
+  INSIGHT_LIFECYCLE,
+  RESEARCH_QUESTION_LIFECYCLE,
+  INTERVIEW_GUIDE_LIFECYCLE,
+  TEST_PLAN_LIFECYCLE,
+  // AI workflow
+  AI_DATASET_LIFECYCLE,
+  AI_GUARDRAIL_LIFECYCLE,
+  MODEL_COMPARISON_LIFECYCLE,
+  PROMPT_VERSION_LIFECYCLE,
+  EVAL_BENCHMARK_LIFECYCLE,
+  // Business Model
+  BUSINESS_MODEL_LIFECYCLE,
+  REVENUE_STREAM_LIFECYCLE,
+  // Customer Success
+  CUSTOMER_HEALTH_SCORE_LIFECYCLE,
+  PLAYBOOK_LIFECYCLE,
+  // Team & Organisation
+  TEAM_OKR_LIFECYCLE,
+  RETROSPECTIVE_LIFECYCLE,
+  DEPENDENCY_LIFECYCLE,
+  ROLE_LIFECYCLE,
+  CAPACITY_PLAN_LIFECYCLE,
+  // Product & Growth
+  VARIANT_LIFECYCLE,
+  GROWTH_CAMPAIGN_LIFECYCLE,
+  // Workspace
+  FRAMEWORK_EXERCISE_LIFECYCLE,
+  COMPOSITION_LIFECYCLE,
+  // ── Template-generated lifecycles ─────────────────────────────────
+  ...TEMPLATE_LIFECYCLES
+];
+function getLifecycleForType(entityType) {
+  return UPG_LIFECYCLES.find((l) => l.entity_type === entityType);
+}
+var UPG_LIFECYCLE_FREE_TYPES = /* @__PURE__ */ new Set([
+  // ── Foundations (3 of 4): a primitive either exists or is deprecated; no
+  //    phase ladder (like metric). `operating_lifecycle`/`operating_stage` are
+  //    static ordered reference data (the loop is a `cyclic` flag, not a state
+  //    machine). `specification` carries a lifecycle. ──
+  "primitive",
+  "operating_lifecycle",
+  "operating_stage",
+  // ── User (5): personas and JTBD atoms are reference data ──────────────────
+  "persona",
+  "job",
+  "job_step",
+  "desired_outcome",
+  "switching_cost",
+  // ── Market Intelligence (7 of 8): competitor landscape is reference data;
+  //    competitor_signal is an append-only dated event (no phase ladder);
+  //    competitive_analysis shipped PUBLISHING lifecycle in Phase C;
+  //    classification_axis and classification_value are reference taxonomy
+  //    atoms with no state machine. ─
+  "competitor",
+  "competitor_feature",
+  "competitor_signal",
+  "market_trend",
+  "market_segment",
+  "classification_axis",
+  "classification_value",
+  // ── Product Specification (1): a configuration_axis is a structural
+  //    DECLARATION (a lever and its closed value set), not a thing that
+  //    progresses through states. Same reading as classification_axis above.
+  "configuration_axis",
+  // ── User Research (5 of 8): participants, quotes, observations,
+  //    clusters, survey responses are immutable data points ────────────────
+  "participant",
+  "observation",
+  "quote",
+  "affinity_cluster",
+  "survey_response",
+  // ── UX Design (3 of 8): journey structural atoms ──────────────────────────
+  "journey_step",
+  "journey_phase",
+  "journey_action",
+  "screen_state",
+  // ── Design System (3 of 7): tokens and annotations are atomic values ────
+  "design_token",
+  "annotation",
+  // ── Brand (4 of 6): colour/typography/imagery/voice are reference atoms ──
+  "brand_colour",
+  "brand_typography",
+  "brand_imagery",
+  // ── Product Specification (4 of 5): criteria, grouping, historical, +
+  //    user_story (the templated promise is a stable design artefact; the paired
+  //    task carries the lifecycle). Re-canon story_statement → user_story at
+  //    v0.7.0/UPG-571. ─
+  "acceptance_criterion",
+  "changelog",
+  "roadmap_theme",
+  "user_story",
+  // ── Strategy: metric is a measurement definition; metric_quality_assessment
+  //    is a point-in-time snapshot; value_stream is a mapped flow;
+  //    constraint carries its own `constraint_status` enum (binding/advisory/
+  //    lifted) as a property; base-node `status` not used.
+  //    vision/mission/capability/outcome get lifecycles in Phase B or C ─────
+  "metric",
+  "metric_quality_assessment",
+  "value_stream",
+  "constraint",
+  // ── Engineering (15 of 17): DDD modelling primitives + infra references.
+  //    root_cause / symptom / fix are investigation findings, not workflows
+  //    (investigation itself has a lifecycle) ────────────────────────────────
+  "aggregate",
+  "domain_entity",
+  "value_object",
+  "command",
+  "read_model",
+  "domain_event",
+  "bounded_context",
+  "api_endpoint",
+  "queue_topic",
+  "build_artifact",
+  "code_repository",
+  "library_dependency",
+  "integration_pattern",
+  "data_flow",
+  "root_cause",
+  "symptom",
+  "fix",
+  // ── Business Model (6 of 9): BMC cells are structural frames ────────────
+  "cost_structure",
+  "unit_economics",
+  "key_resource",
+  "key_activity",
+  "customer_relationship",
+  "distribution_channel",
+  // ── Go-To-Market (8 of 13): positioning/ICP/territory/sales_motion are
+  //    configuration; objection/rebuttal/proof_point are catalog entries ───
+  "ideal_customer_profile",
+  "positioning",
+  "sales_motion",
+  "territory",
+  "objection",
+  "rebuttal",
+  "proof_point",
+  // ── Team & Organisation (7 of 11): org structural atoms ───────────────────
+  "team",
+  "stakeholder",
+  "person",
+  "department",
+  "skill",
+  "ceremony",
+  // ── Data & Analytics (4 of 10): lineage and domain containers, plus
+  //    atomic definitions ────────────────────────────────────────────────────
+  "data_lineage",
+  "data_domain",
+  "data_quality_rule",
+  // ── AI (3 of 10): traces and cost trackers are append-only; model
+  //    comparison snapshots are immutable ───────────────────────────────────
+  "ai_cost_tracker",
+  "ai_trace",
+  // ── Automation (2 of 6): approvals and artifacts are ledger entries ──────
+  "approval_record",
+  "workflow_artifact",
+  // ── Growth (7 of 9): funnels and attribution are structural definitions;
+  //    cohorts/segments are computed snapshots ────────────────────────────
+  "funnel",
+  "funnel_step",
+  "acquisition_channel",
+  "cohort",
+  "behavioral_segment",
+  "growth_loop",
+  "attribution_model",
+  // ── Sales (5 of 6): pipeline structure + accounts/contacts + forecast
+  //    snapshots. Only `deal` has a lifecycle (Phase B SALES_DEAL template) ─
+  "account",
+  "contact",
+  "pipeline_sales",
+  "pipeline_stage",
+  "forecast",
+  // ── Customer Success (5 of 9): journey structure + derived values ────────
+  "customer_journey_stage",
+  "touchpoint",
+  "churn_reason",
+  "service_level_agreement",
+  // ── DevOps (5 of 10): indicators and budgets are measurement references;
+  //    strategies and pipelines are configuration ──────────────────────────
+  "service_level_indicator",
+  "service_level_objective",
+  "error_budget",
+  "ci_pipeline",
+  "release_strategy",
+  // ── Security (1 of 5): data classification is a reference label ──────────
+  "data_classification",
+  // ── Accessibility (2 of 4): standards and annotations ─────────────────────
+  "a11y_standard",
+  "a11y_annotation",
+  // ── Testing (3 of 5): regression tests are reference definitions; test
+  //    results and coverage reports are immutable records ───────────────────
+  "regression_test",
+  "test_coverage_report",
+  "test_result",
+  // ── Customer Feedback (2 of 3): themes and votes are atomic data points ──
+  "feedback_theme",
+  "feedback_vote",
+  // ── Pricing (2 of 4): trial and paywall are configuration ─────────────────
+  "trial_config",
+  "paywall",
+  // ── Content (2 of 5): calendars and themes are planning configuration ────
+  "content_calendar",
+  "content_theme",
+  // ── Legal (2 of 3): legal_entity is an org; contract_clause is an atom
+  //    of a contract (which has its own lifecycle) ───────────────────────────
+  "legal_entity",
+  "contract_clause",
+  // ── Portfolio (3 of 3): structural containers ─────────────────────────────
+  "organization",
+  "portfolio",
+  "product_area",
+  // ── Program Management (2 of 3): allocations and registers are tracking
+  //    containers ────────────────────────────────────────────────────────────
+  "resource_allocation",
+  "risk_register",
+  // ── Localisation (4 of 5): translation keys, configs, and regional
+  //    adaptations are reference data ────────────────────────────────────────
+  "translation_key",
+  "locale_config",
+  "cultural_adaptation",
+  "regional_pricing",
+  // ── Marketing (1 of 4): SEO keywords are tracked reference terms ─────────
+  "seo_keyword",
+  // ── Ecosystem (2 of 2): partner tiers and rev-share terms are config ─────
+  "partner_tier",
+  "partner_revenue_share",
+  // ── Validation (2 of 4): evidence + learning are data points captured
+  //    from experiment_runs (which have lifecycles); hypothesis_evidence was
+  //    lifecycle-free here but is deprecated at v0.4.0 ──────────────────────────────────────
+  "evidence",
+  "learning",
+  // ── Workspace (1 of 4): a capture is a fact about a moment, not a workflow.
+  //    It is taken, and from then on it either still matches its subject or it
+  //    does not — which is what `content_hash` answers, not a phase. ─────────
+  "capture"
+]);
+function isLifecycleFreeType(entityType) {
+  return UPG_LIFECYCLE_FREE_TYPES.has(entityType);
+}
+var UPG_LIFECYCLE_PLANNED_TYPES = /* @__PURE__ */ new Set([
+  // Phase B cleared this set entirely. Every type that was triaged
+  // into Phase B/C/D under now either has a lifecycle in
+  // `UPG_LIFECYCLES` or is documented as lifecycle-free in
+  // `UPG_LIFECYCLE_FREE_TYPES`.
+  //
+  // Reintroduce entries here when a new entity type is added to the spec
+  // and decided to be lifecycle-bearing but its phases have not yet been
+  // designed. The `10-lifecycle-coverage` audit will surface uncovered
+  // active types until they're either implemented or moved to the
+  // free-types set.
+]);
+function isLifecyclePlannedType(entityType) {
+  return UPG_LIFECYCLE_PLANNED_TYPES.has(entityType);
+}
+function getLifecycleRenderShape(entityType) {
+  const lifecycle = getLifecycleForType(entityType);
+  if (!lifecycle) return null;
+  const terminalSet = new Set(lifecycle.terminal_phases);
+  const phaseIndex = new Map(lifecycle.phases.map((p, i) => [p.id, i]));
+  const states = lifecycle.phases.map((phase) => ({
+    id: phase.id,
+    label: phase.label,
+    description: phase.description,
+    terminal: terminalSet.has(phase.id)
+  }));
+  const transitions = [];
+  for (const phase of lifecycle.phases) {
+    const fromTerminal = terminalSet.has(phase.id);
+    for (const to of phase.transitions_to) {
+      const toTerminal = terminalSet.has(to);
+      let kind;
+      if (fromTerminal && !toTerminal) {
+        kind = "reopen";
+      } else if (toTerminal && !fromTerminal) {
+        kind = "terminal";
+      } else {
+        const fromIdx = phaseIndex.get(phase.id) ?? 0;
+        const toIdx = phaseIndex.get(to) ?? 0;
+        kind = toIdx < fromIdx ? "backward" : "forward";
+      }
+      transitions.push({ from: phase.id, to, kind });
+    }
+  }
+  return {
+    entity_type: lifecycle.entity_type,
+    ...lifecycle.template_id !== void 0 && { template_id: lifecycle.template_id },
+    states,
+    transitions,
+    initial_state: lifecycle.initial_phase
+  };
+}
+
+// src/catalog/legacy-product-stages.ts
+var LEGACY_PRODUCT_STAGES = Object.freeze({
+  idea: "concept"
+});
+function migrateProductStage(stage) {
+  if (stage === void 0 || stage === null) {
+    return void 0;
+  }
+  if (typeof stage !== "string") {
+    return stage;
+  }
+  const lower = stage.toLowerCase();
+  const mapped = LEGACY_PRODUCT_STAGES[lower];
+  return mapped ?? stage;
+}
+function isLegacyProductStage(stage) {
+  return typeof stage === "string" && stage.toLowerCase() in LEGACY_PRODUCT_STAGES;
+}
+
+// src/shapes/base-node.ts
+var BASE_NODE_FIELD_PRESENCE = {
+  id: true,
+  type: true,
+  title: true,
+  slug: true,
+  aliases: true,
+  key: true,
+  description: true,
+  tags: true,
+  status: true,
+  archived: true,
+  archived_at: true,
+  source_id: true,
+  source_type: true,
+  mapping_confidence: true,
+  external_tool: true,
+  external_ref: true,
+  external_id: true,
+  external_links: true,
+  created_at: true,
+  updated_at: true,
+  properties: true
 };
-var UPG_LIFECYCLES = [
-  // Product (root)
-  PRODUCT_LIFECYCLE,
-  // Foundations (0.9.12)
-  SPECIFICATION_LIFECYCLE,
-  // Discovery & Validation
-  NEED_LIFECYCLE,
-  OPPORTUNITY_LIFECYCLE,
-  SOLUTION_LIFECYCLE,
-  EXPERIMENT_PLAN_LIFECYCLE,
-  RESEARCH_PLAN_LIFECYCLE,
-  FEEDBACK_PROGRAM_LIFECYCLE,
-  FEATURE_REQUEST_LIFECYCLE,
-  BETA_PROGRAM_LIFECYCLE,
-  USER_ADVISORY_BOARD_LIFECYCLE,
-  // Strategy & Product Specification
-  OUTCOME_LIFECYCLE,
-  VISION_LIFECYCLE,
-  MISSION_LIFECYCLE,
-  CAPABILITY_LIFECYCLE,
-  OBJECTIVE_LIFECYCLE,
-  KEY_RESULT_LIFECYCLE,
-  STRATEGIC_THEME_LIFECYCLE,
-  INITIATIVE_LIFECYCLE,
-  STRATEGIC_PILLAR_LIFECYCLE,
-  STRATEGIC_QUESTION_LIFECYCLE,
-  FEATURE_AREA_LIFECYCLE,
-  FEATURE_LIFECYCLE,
-  // user_story is lifecycle-free (declared in UPG_LIFECYCLE_FREE_TYPES below).
-  // story_task lifecycle removed v0.4.0; collapsed into task. task + epic are
-  // now WORK_ITEM-template-derived (UPG-690, 0.21.0) — see TEMPLATE_LIFECYCLES.
-  RELEASE_LIFECYCLE,
-  ROADMAP_ITEM_LIFECYCLE,
-  PLANNING_CYCLE_LIFECYCLE,
-  IP_ASSET_LIFECYCLE,
-  CONTRACT_LIFECYCLE,
-  DESIGN_CONCEPT_LIFECYCLE,
-  BRAND_IDENTITY_LIFECYCLE,
-  SCREEN_LIFECYCLE,
-  SURFACE_LIFECYCLE,
-  // Engineering & Operations
-  SERVICE_LIFECYCLE,
-  DEPLOYMENT_LIFECYCLE,
-  FEATURE_FLAG_LIFECYCLE,
-  INVESTIGATION_LIFECYCLE,
-  EXTERNAL_API_LIFECYCLE,
-  DATABASE_SCHEMA_LIFECYCLE,
-  INCIDENT_LIFECYCLE,
-  SECURITY_CONTROL_LIFECYCLE,
-  DATA_PIPELINE_LIFECYCLE,
-  AI_MODEL_LIFECYCLE,
-  WORKFLOW_RUN_LIFECYCLE,
-  AGENT_DEFINITION_LIFECYCLE,
-  AGENT_SESSION_LIFECYCLE,
-  REVIEW_GATE_LIFECYCLE,
-  TEST_SUITE_LIFECYCLE,
-  TEST_CASE_LIFECYCLE,
-  // ── Phase B hand-authored ─────────────────────────────────────────
-  // Research + Validation
-  INSIGHT_LIFECYCLE,
-  RESEARCH_QUESTION_LIFECYCLE,
-  INTERVIEW_GUIDE_LIFECYCLE,
-  TEST_PLAN_LIFECYCLE,
-  // AI workflow
-  AI_DATASET_LIFECYCLE,
-  AI_GUARDRAIL_LIFECYCLE,
-  MODEL_COMPARISON_LIFECYCLE,
-  PROMPT_VERSION_LIFECYCLE,
-  EVAL_BENCHMARK_LIFECYCLE,
-  // Business Model
-  BUSINESS_MODEL_LIFECYCLE,
-  REVENUE_STREAM_LIFECYCLE,
-  // Customer Success
-  CUSTOMER_HEALTH_SCORE_LIFECYCLE,
-  PLAYBOOK_LIFECYCLE,
-  // Team & Organisation
-  TEAM_OKR_LIFECYCLE,
-  RETROSPECTIVE_LIFECYCLE,
-  DEPENDENCY_LIFECYCLE,
-  ROLE_LIFECYCLE,
-  CAPACITY_PLAN_LIFECYCLE,
-  // Product & Growth
-  VARIANT_LIFECYCLE,
-  GROWTH_CAMPAIGN_LIFECYCLE,
-  // Workspace
-  FRAMEWORK_EXERCISE_LIFECYCLE,
-  COMPOSITION_LIFECYCLE,
-  // ── Template-generated lifecycles ─────────────────────────────────
-  ...TEMPLATE_LIFECYCLES
+var UPG_BASE_NODE_FIELDS = Object.freeze(
+  Object.keys(BASE_NODE_FIELD_PRESENCE)
+);
+var UPG_BASE_NODE_FIELD_SET = new Set(UPG_BASE_NODE_FIELDS);
+var UPG_BASE_NODE_SPECIAL_MERGE_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "type",
+  "slug",
+  "aliases",
+  "properties"
+]);
+
+// src/shapes/document.ts
+var UPG_CROSS_ONLY_EDGE_TYPES = [
+  // Peer overlap: "these two products share / overlap on this thing." Symmetric,
+  // no canonical instance_of identity. shares_job / shares_need are the job/need
+  // siblings of the persona/competitor/metric peers (connective layer, 0.13.1).
+  "shares_persona",
+  "shares_competitor",
+  "shares_metric",
+  "shares_job",
+  "shares_need",
+  // Product-to-product relationships.
+  "depends_on_product",
+  // runtime dependency (built-on / dogfood), not containment
+  "cannibalises",
+  "succeeds",
+  "hosts",
+  // host runs the hosted product inside itself (container -> contained)
+  // OKR / measurement rollup primitives: the cascade ACROSS products (subordinate
+  // -> superior). `contributes_to` rolls a product strategy entity up to a higher-
+  // level one; `rolls_up_to` feeds a product metric into a higher-level north-star.
+  "contributes_to",
+  "rolls_up_to",
+  // Canonical instance + area-to-audience: the target lives in the portfolio
+  // `registry` section (`registry/{node_id}`). `instance_of` is same-type
+  // canonical-to-instance; the area edges are minted via `link_area_to_audience`.
+  "instance_of",
+  "area_serves_persona",
+  "area_targets_market_segment",
+  // Foundations (0.9.12): a product-graph entity links to a canonical specification
+  // or primitive. Registry-internal spec-to-spec links are catalog edges, not these.
+  //
+  // CORRECTED 0.34.0 — the target contract. This comment said `registry/{node_id}`,
+  // "same shape as instance_of". Every live instance disagrees: all three in the
+  // field target `{product_id}/{node_id}`, and the portfolio's `registry` section
+  // is EMPTY. A reader following the old sentence would look for a registry entry
+  // that has never existed. Both target forms are legitimate — a specification held
+  // as a canonical in the registry, or one held inside the product graph that owns
+  // it — and the field has so far only produced the second.
+  //
+  // THE GAP THIS TIER LEAVES, restated 0.34.0 because the 0.33.0 wording named a
+  // case no graph instantiates. It is NOT "a specification in a graph with no
+  // portfolio around it". It is the HOLDER PRODUCT, and it is live today: the
+  // product graph that HOLDS a specification node has three sibling products
+  // reaching it through this tier and no way to state its own relation to it,
+  // because the cross tier requires two distinct products and there is no
+  // within-graph conformance edge. Not closed in 0.34.0. The verb the live case
+  // wants is `defines` rather than `conforms_to` — a product does not conform to
+  // the specification it authors — and one instance of evidence is not enough to
+  // mint a catalog edge in the area that cost 0.33.0 its shape mid-build. The
+  // condition is the second holder-product instance, or any single-product graph
+  // modelling a specification it conforms to.
+  "product_implements_specification",
+  "product_exposes_specification",
+  "feature_conforms_to_specification",
+  "api_contract_speaks_specification",
+  "product_exposes_primitive",
+  "feature_manipulates_primitive",
+  "primitive_stored_as_data_type"
 ];
-function getLifecycleForType(entityType) {
-  return UPG_LIFECYCLES.find((l) => l.entity_type === entityType);
+var UPG_CROSS_EDGE_TYPES = [
+  ...UPG_CROSS_ONLY_EDGE_TYPES,
+  ...UPG_CROSS_ELIGIBLE_CATALOG_EDGE_TYPES
+];
+var REGISTRY_PRODUCT_ID = "registry";
+var UPG_PORTFOLIO_KINDS = ["owned", "watched", "strategic", "internal", "gtm"];
+
+// src/registry/entity-type-resolution.ts
+var TYPES = getTypes();
+var TYPES_SET = new Set(TYPES);
+var UnknownEntityTypeError = class extends Error {
+  suggestions;
+  rawType;
+  constructor(rawType, suggestions) {
+    const suffix = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?` : "";
+    super(`Unknown entity type: "${rawType}".${suffix}`);
+    this.name = "UnknownEntityTypeError";
+    this.rawType = rawType;
+    this.suggestions = suggestions;
+  }
+};
+function withinEditDistance1(a, b) {
+  if (a === b) return true;
+  const al = a.length;
+  const bl = b.length;
+  if (Math.abs(al - bl) > 1) return false;
+  let i = 0;
+  let j = 0;
+  let edits = 0;
+  while (i < al && j < bl) {
+    if (a[i] !== b[j]) {
+      if (++edits > 1) return false;
+      if (al > bl) i++;
+      else if (bl > al) j++;
+      else {
+        i++;
+        j++;
+      }
+    } else {
+      i++;
+      j++;
+    }
+  }
+  if (i < al || j < bl) edits++;
+  return edits <= 1;
 }
-var UPG_LIFECYCLE_FREE_TYPES = /* @__PURE__ */ new Set([
-  // ── Foundations (3 of 4): a primitive either exists or is deprecated; no
-  //    phase ladder (like metric). `operating_lifecycle`/`operating_stage` are
-  //    static ordered reference data (the loop is a `cyclic` flag, not a state
-  //    machine). `specification` carries a lifecycle. ──
-  "primitive",
-  "operating_lifecycle",
-  "operating_stage",
-  // ── User (5): personas and JTBD atoms are reference data ──────────────────
-  "persona",
-  "job",
-  "job_step",
-  "desired_outcome",
-  "switching_cost",
-  // ── Market Intelligence (7 of 8): competitor landscape is reference data;
-  //    competitor_signal is an append-only dated event (no phase ladder);
-  //    competitive_analysis shipped PUBLISHING lifecycle in Phase C;
-  //    classification_axis and classification_value are reference taxonomy
-  //    atoms with no state machine. ─
-  "competitor",
-  "competitor_feature",
-  "competitor_signal",
-  "market_trend",
-  "market_segment",
-  "classification_axis",
-  "classification_value",
-  // ── Product Specification (1): a configuration_axis is a structural
-  //    DECLARATION (a lever and its closed value set), not a thing that
-  //    progresses through states. Same reading as classification_axis above.
-  "configuration_axis",
-  // ── User Research (5 of 8): participants, quotes, observations,
-  //    clusters, survey responses are immutable data points ────────────────
-  "participant",
-  "observation",
-  "quote",
-  "affinity_cluster",
-  "survey_response",
-  // ── UX Design (3 of 8): journey structural atoms ──────────────────────────
-  "journey_step",
-  "journey_phase",
-  "journey_action",
-  "screen_state",
-  // ── Design System (3 of 7): tokens and annotations are atomic values ────
-  "design_token",
-  "annotation",
-  // ── Brand (4 of 6): colour/typography/imagery/voice are reference atoms ──
-  "brand_colour",
-  "brand_typography",
-  "brand_imagery",
-  // ── Product Specification (4 of 5): criteria, grouping, historical, +
-  //    user_story (the templated promise is a stable design artefact; the paired
-  //    task carries the lifecycle). Re-canon story_statement → user_story at
-  //    v0.7.0/UPG-571. ─
-  "acceptance_criterion",
-  "changelog",
-  "roadmap_theme",
-  "user_story",
-  // ── Strategy: metric is a measurement definition; metric_quality_assessment
-  //    is a point-in-time snapshot; value_stream is a mapped flow;
-  //    constraint carries its own `constraint_status` enum (binding/advisory/
-  //    lifted) as a property; base-node `status` not used.
-  //    vision/mission/capability/outcome get lifecycles in Phase B or C ─────
-  "metric",
-  "metric_quality_assessment",
-  "value_stream",
-  "constraint",
-  // ── Engineering (15 of 17): DDD modelling primitives + infra references.
-  //    root_cause / symptom / fix are investigation findings, not workflows
-  //    (investigation itself has a lifecycle) ────────────────────────────────
-  "aggregate",
-  "domain_entity",
-  "value_object",
-  "command",
-  "read_model",
-  "domain_event",
-  "bounded_context",
-  "api_endpoint",
-  "queue_topic",
-  "build_artifact",
-  "code_repository",
-  "library_dependency",
-  "integration_pattern",
-  "data_flow",
-  "root_cause",
-  "symptom",
-  "fix",
-  // ── Business Model (6 of 9): BMC cells are structural frames ────────────
-  "cost_structure",
-  "unit_economics",
-  "key_resource",
-  "key_activity",
-  "customer_relationship",
-  "distribution_channel",
-  // ── Go-To-Market (8 of 13): positioning/ICP/territory/sales_motion are
-  //    configuration; objection/rebuttal/proof_point are catalog entries ───
-  "ideal_customer_profile",
-  "positioning",
-  "sales_motion",
-  "territory",
-  "objection",
-  "rebuttal",
-  "proof_point",
-  // ── Team & Organisation (7 of 11): org structural atoms ───────────────────
-  "team",
-  "stakeholder",
+function resolveEntityType(rawType) {
+  if (typeof rawType !== "string" || rawType.length === 0) {
+    throw new UnknownEntityTypeError(String(rawType ?? ""), []);
+  }
+  if (TYPES_SET.has(rawType)) {
+    return { canonical: rawType };
+  }
+  const replacement = getReplacementType(rawType);
+  if (replacement && TYPES_SET.has(replacement)) {
+    return { canonical: replacement, alias: { from: rawType, to: replacement } };
+  }
+  const suggestions = [];
+  for (const t of TYPES) {
+    if (withinEditDistance1(t, rawType)) suggestions.push(t);
+    if (suggestions.length >= 5) break;
+  }
+  throw new UnknownEntityTypeError(rawType, suggestions);
+}
+
+// src/grammar/hierarchy.ts
+var UPG_VALID_CHILDREN = {
+  // ── Foundations (0.9.12): registry canonicals that self-nest. A
+  //    specification extends a specification (a dialect of a parent spec); a
+  //    primitive composes primitives (a block contains spans). These back the
+  //    hierarchy-classified specification_extends_specification /
+  //    primitive_composes_primitive catalog edges.
+  specification: ["specification"],
+  primitive: ["primitive"],
+  // An operating_lifecycle (e.g. the content-ops lifecycle) contains its ordered
+  // operating_stage children. Backs the operating_lifecycle_contains_operating_stage edge.
+  operating_lifecycle: ["operating_stage"],
+  // ── Product (root) ─────────────────────────────────────────────────────────
+  product: [
+    // Strategy
+    "vision",
+    "outcome",
+    "objective",
+    "metric",
+    "decision",
+    "constraint",
+    // User
+    "persona",
+    // Discovery (via outcome children)
+    // Validation (via hypothesis children)
+    // Market Intelligence
+    "competitor",
+    "market_trend",
+    "market_segment",
+    "competitive_analysis",
+    // User Research
+    "research_study",
+    // Experience Design
+    "user_journey",
+    "user_flow",
+    "wireframe",
+    "screen",
+    // Design System
+    "design_system",
+    "design_component",
+    // Brand Identity
+    "brand_identity",
+    // Product Specification
+    "feature",
+    "feature_area",
+    "release",
+    "roadmap",
+    "roadmap_theme",
+    "planning_cycle",
+    // Configuration (0.30.0): the levers whose values select which surface tree
+    // the product renders. Few per product, and top-level because an axis is a
+    // product-wide fact rather than a child of any one feature or surface.
+    "configuration_axis",
+    // Classification (0.32.0): the product's own taxonomies — the grouped-label
+    // case, one named group over a set of values. Same reasoning as the
+    // configuration axis above, and until now the only parent a
+    // classification_axis could have was a competitive_analysis.
+    "classification_axis",
+    // Engineering
+    "bounded_context",
+    "code_repository",
+    "integration_pattern",
+    "external_api",
+    "data_flow",
+    // Growth
+    "funnel",
+    "acquisition_channel",
+    "cohort",
+    "behavioral_segment",
+    "growth_loop",
+    "attribution_model",
+    // Business Model
+    "business_model",
+    // Go-To-Market
+    "gtm_strategy",
+    // Team & Organisation
+    // `person` is containment-free (see UPG_CONTAINMENT_FREE_TYPES below)
+    // (referenced via edges, not nested under product)
+    "team",
+    "stakeholder",
+    "department",
+    // Data & Analytics
+    "data_source",
+    "event_schema",
+    "dashboard",
+    "data_domain",
+    "glossary_term",
+    // Content & Knowledge
+    "content_piece",
+    "knowledge_base_article",
+    "brand_asset",
+    "document",
+    "documentation_template",
+    // Legal
+    "legal_entity",
+    "privacy_policy",
+    // Compliance
+    "compliance_requirement",
+    "risk",
+    "data_contract",
+    "audit_log_policy",
+    "compliance_framework",
+    // DevOps & Platform
+    "service_level_objective",
+    "incident",
+    "runbook",
+    "monitor",
+    "ci_pipeline",
+    "release_strategy",
+    "on_call_rotation",
+    "infrastructure_component",
+    // Security
+    "threat_model",
+    "security_control",
+    "security_policy",
+    "penetration_test",
+    "security_review",
+    "data_classification",
+    "access_policy",
+    // Accessibility
+    "a11y_standard",
+    "a11y_audit",
+    "a11y_annotation",
+    // Quality Assurance
+    "test_plan",
+    "test_suite",
+    "qa_session",
+    "test_coverage_report",
+    "test_environment",
+    // Customer Feedback
+    "feedback_program",
+    "user_advisory_board",
+    "beta_program",
+    // Pricing & Packaging
+    "pricing_strategy",
+    // AI & Machine Learning
+    "ai_model",
+    "model_comparison",
+    // Workflows & Agents
+    "workflow_template",
+    "agent_definition",
+    // Sales & Revenue
+    "pipeline_sales",
+    "account",
+    "lead",
+    "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",
+    "event",
+    "community_initiative",
+    // Customer Success
+    "support_ticket",
+    "customer_feedback",
+    "churn_reason",
+    "customer_health_score",
+    "playbook",
+    "service_level_agreement",
+    "success_milestone",
+    "service_blueprint",
+    "nps_campaign",
+    // Localisation
+    "locale",
+    "locale_config",
+    // Customer Education
+    "education_program",
+    // Partners & Ecosystem
+    "partner_program",
+    "api_ecosystem",
+    "developer_portal",
+    // Portfolio
+    // (UPG-677) product no longer lists product_area as a child: the
+    // product↔product_area containment is the single direction
+    // product_area_contains_product (product_area → product). The inverse
+    // product_categorised_in_product_area edge was collapsed.
+    // Workspace
+    "workspace"
+  ],
+  // ── Metric & Outcome hierarchy ──────────────────────────────────────────────
+  outcome: ["metric", "opportunity", "feature"],
+  // ── User & Jobs hierarchy ───────────────────────────────────────────────────
+  persona: ["job", "need", "switching_cost", "desired_outcome"],
+  job: ["need", "desired_outcome", "job_step"],
+  // ── Discovery hierarchy ─────────────────────────────────────────────────────
+  opportunity: ["solution", "design_concept", "feasibility_study", "design_sprint"],
+  // solutions now propose hypothesis (the templated
+  // belief), not the legacy hypothesis type.
+  solution: ["hypothesis", "prototype", "metric"],
+  // ── Validation hierarchy ────────────────────────────────────────────────────
+  // (UPG-664) The validation chain is a single-parent line:
+  //   hypothesis ▷ experiment_plan ▷ experiment ▷ experiment_run.
+  // hypothesis is canonical (hypothesis_evidence collapsed into evidence;
+  // relationship expressed via hypothesis_has_evidence edge; evidence.direction
+  // carries supports/refutes/neutral semantics). `test_plan` re-homed to the
+  // QA/testing domain (UPG-678), so it is no longer a hypothesis child.
+  hypothesis: ["experiment_plan", "research_plan", "evidence"],
+  // experiment_plan is the canonical validation PLAN (graduated stable,
+  // UPG-664). It designs the experiment it produces; the plan owns the
+  // experiment in the containment line. It also retains experiment_run as a
+  // child for the v0.2.6 split-migration path
+  // (`experiment_plan_ran_as_experiment_run`), where a legacy experiment routes
+  // directly to a plan + run pair.
+  experiment_plan: ["experiment", "experiment_run"],
+  // experiment is the canonical structured test. It owns its run(s) and the
+  // learning/evidence it produces. The optional experiment_run child captures
+  // the multi-run / replication case.
+  experiment: ["experiment_run", "learning", "evidence"],
+  // experiment_run carries learning/evidence/metric children (run produces
+  // evidence) and self-nests for replications/multi-armed runs (V9: this is
+  // where self-nesting genuinely lives, not on `experiment`).
+  experiment_run: ["learning", "evidence", "metric", "experiment_run"],
+  // ── OKR hierarchy ──────────────────────────────────────────────────────────
+  // strategic_question (0.17.4): an open coordination question raised under an
+  // objective (objective_raises_strategic_question, hierarchy).
+  objective: ["key_result", "metric", "strategic_question"],
+  key_result: ["metric"],
+  // ── Strategic cascade: vision → mission → strategic_pillar → strategic_theme →
+  //    { initiative, objective } ───────────────────────────────────────────────
+  //
+  // strategic_pillar vs strategic_theme (UPG-692 T3.3 — distinct cascade levels,
+  // NOT duplicates; sharpened rather than merged):
+  //   - strategic_pillar = a DURABLE structural division of the strategy. A
+  //     standing area the org organises around for years (e.g. "Structured
+  //     content", "Developer experience"). Few, long-lived; time_horizon is
+  //     multi-year / open-ended; carries its own `success_indicator`.
+  //   - strategic_theme = a TIME-BOUND thrust WITHIN a pillar. The current bet
+  //     for a period (e.g. "Go AI-native this year"). More numerous, rotates;
+  //     time_horizon is bounded (Q / FY); has NO `success_indicator` because it
+  //     is measured through its child objectives (strategic_theme_contains_objective).
+  //     That success-measurement asymmetry is the load-bearing distinction.
+  vision: ["mission"],
+  mission: ["strategic_pillar"],
+  // 0.20.1: metric added as a strategic_pillar child, backing
+  // strategic_pillar_measured_by_metric (hierarchy) — the pillar's own
+  // north-star, mirrored from objective: ['key_result', 'metric', ...] one
+  // level down the cascade.
+  strategic_pillar: ["strategic_theme", "capability", "value_stream", "decision", "metric"],
+  // v0.5.4 (UPG-511): objectives are the specific quarterly bets *within* a
+  // strategic theme. The theme is the multi-quarter focus area; objectives are
+  // subordinate. Pairs with `strategic_theme_contains_objective` in the edge
+  // catalog (hierarchy, strategic_theme → objective, reverse_verb: rolls_up_to;
+  // renamed from objective_rolls_up_to_strategic_theme in UPG-676).
+  strategic_theme: ["initiative", "objective"],
+  initiative: ["assumption", "strategic_question"],
+  // v0.5.2 (UPG-528): capability decomposes into sub-capabilities (Wardley
+  // value-chain spine) and is realised by user-facing features. Pairs with
+  // `capability_depends_on_capability` and `capability_implemented_by_feature`
+  // in the edge catalogue. The self-loop guard (UPG-520) keeps A → A refused;
+  // A → B between distinct capabilities is the supported decomposition.
+  capability: ["capability", "feature"],
+  // ── Market hierarchy ────────────────────────────────────────────────────────
+  // competitive_analysis hosts classification axes (its dimensions);
+  // each axis hosts its values; values are reusable across the row and column
+  // dossiers of a 2-axis matrix.
+  competitive_analysis: ["competitor", "market_trend", "market_segment", "classification_axis"],
+  competitor: ["competitor_feature", "competitor_signal"],
+  classification_axis: ["classification_value"],
+  // ── UX Research hierarchy ───────────────────────────────────────────────────
+  research_study: [
+    "participant",
+    "observation",
+    "affinity_cluster",
+    "research_question",
+    "interview_guide",
+    "insight",
+    "survey_response"
+  ],
+  observation: ["quote"],
+  // F6 (UPG-672): affinity_cluster owns the observations it groups, in addition
+  // to the insights it synthesises. Pairs with `affinity_cluster_groups_observation`
+  // in the edge catalog (hierarchy). An observation can be both directly owned by
+  // its research_study and grouped under an affinity_cluster (multi-parent grammar).
+  affinity_cluster: ["insight", "observation"],
+  // insight refines into insight; a raw insight can be distilled
+  // into a more specific insight (refines_into chain).
+  // v0.5.8 (UPG-528 Part 2d): insights own their evidencing quotes;
+  // parallel to `observation: ['quote']`. Research-synthesis canon.
+  // Pairs with `insight_evidenced_by_quote` in the edge catalog.
+  // ── Design hierarchy ────────────────────────────────────────────────────────
+  // (UPG-663, v0.9.2) A user_journey owns its steps (the stable 0.1.0 spine)
+  // and carries phases as a non-owning band overlay. A journey_phase is NO
+  // LONGER a containment parent of journey_step: it SPANS steps via the
+  // `journey_phase_spans_journey_step` edge (mirroring the marketing
+  // `customer_journey_stage_spans_journey_step` precedent), so each step has
+  // exactly one containment parent and the journey has one canonical step list.
+  user_journey: ["journey_step", "journey_phase"],
+  journey_step: ["journey_action"],
+  // v0.5.8 (UPG-528 Part 2d): insights own their evidencing quotes;
+  // parallel to `observation: ['quote']`. Research-synthesis canon
+  // (insight ← quote evidencing) extends quote's hierarchy parents to
+  // both observation (raw-capture parent) and insight (synthesis parent).
+  // Pairs with `insight_evidenced_by_quote` in the edge catalog.
+  insight: ["design_question", "insight", "quote"],
+  // v0.5.2 (UPG-528): need anchors a Wardley value chain; capabilities
+  // fulfil the need at the chain top. Cross-domain hierarchy (need ∈ Design,
+  // capability ∈ Strategy) is intentional: Wardley analysis starts from a
+  // user need and decomposes into the capabilities required to fulfil it.
+  need: ["design_question", "capability"],
+  design_question: ["design_concept"],
+  design_concept: ["prototype", "wireframe"],
+  design_component: [
+    "design_token",
+    "design_pattern",
+    "design_guideline",
+    "interaction_spec",
+    "design_component"
+  ],
+  // self-nesting for atomic hierarchy (organism → molecule → atom)
+  prototype: ["annotation"],
+  // ── Brand hierarchy ─────────────────────────────────────────────────────────
+  brand_identity: [
+    "brand_colour",
+    "brand_typography",
+    "brand_asset",
+    "brand_voice",
+    "brand_logo",
+    "brand_imagery"
+  ],
+  // ── Product Specification hierarchy ─────────────────────────────────────────
+  // story_task collapsed into canonical task. feature now owns
+  // task directly; story-derived tasks implement user_story via
+  // task_implements_user_story edge.
+  feature: ["epic", "bug", "task"],
+  feature_area: ["feature", "feature_area"],
+  // epic owns user_story (the templated promise) and, mirroring feature, may
+  // also directly contain bug/task — heterogeneous imported tickets that belong
+  // to one epic rather than the feature as a whole (feedback df99026a).
+  epic: ["user_story", "bug", "task"],
+  user_story: ["acceptance_criterion"],
+  task: ["task"],
+  // planning_cycle (0.20.0): the cadence axis self-nests (a program-increment
+  // contains iterations; a cycle contains its cooldown) via
+  // planning_cycle_contains_planning_cycle. It does NOT contain user_story as a
+  // child: scheduling work into a cycle is the semantic, deliberate-only
+  // planning_cycle_schedules_work_item edge, so the item keeps its feature/epic
+  // containment parent and is merely referenced by the cycle.
+  planning_cycle: ["planning_cycle"],
+  // ── Engineering hierarchy ───────────────────────────────────────────────────
+  bounded_context: [
+    "service",
+    "domain_event",
+    "decision",
+    "data_model",
+    "aggregate",
+    "read_model",
+    "code_repository",
+    "integration_pattern",
+    "external_api",
+    "data_flow",
+    // v0.5.7 (UPG-528 Part 2c): BCs publish api_contracts as their "published
+    // language" (DDD canon). api_contract has two valid hierarchy parents now:
+    // service (per-service exposure) AND bounded_context (BC-level surface).
+    "api_contract"
+  ],
+  service: [
+    "api_contract",
+    "technical_debt_item",
+    "feature_flag",
+    "deployment",
+    "api_endpoint",
+    "database_schema",
+    "queue_topic",
+    "build_artifact",
+    "library_dependency"
+  ],
+  // v0.5.1 (UPG-517 C2): contracts contain their endpoints. Service still
+  // serves endpoints directly (legacy / non-contract endpoints); both
+  // parent-child paths coexist.
+  api_contract: ["api_endpoint"],
+  decision: ["technical_debt_item"],
+  aggregate: ["domain_entity", "value_object", "command"],
+  // ── Growth hierarchy ────────────────────────────────────────────────────────
+  funnel: ["funnel_step"],
+  acquisition_channel: ["growth_campaign"],
+  growth_campaign: ["experiment_plan", "variant"],
+  // ── Business Model hierarchy ─────────────────────────────────────────────────
+  business_model: [
+    "value_proposition",
+    "revenue_stream",
+    "cost_structure",
+    "unit_economics",
+    "partnership",
+    "key_resource",
+    "key_activity",
+    "customer_relationship",
+    "distribution_channel"
+  ],
+  revenue_stream: ["pricing_tier"],
+  // ── Go-To-Market hierarchy ───────────────────────────────────────────────────
+  gtm_strategy: [
+    "ideal_customer_profile",
+    "positioning",
+    "launch",
+    "content_strategy",
+    "sales_motion",
+    "competitive_battle_card",
+    "demand_gen_program",
+    "territory"
+  ],
+  positioning: ["messaging", "objection", "proof_point"],
+  value_proposition: ["objection", "proof_point"],
+  competitive_battle_card: ["objection"],
+  objection: ["rebuttal"],
+  rebuttal: ["proof_point"],
+  // ── Team & Organisation hierarchy ───────────────────────────────────────────
+  department: ["team", "stakeholder"],
+  team: [
+    "role",
+    "team_okr",
+    "retrospective",
+    "dependency",
+    "skill",
+    "ceremony",
+    "capacity_plan",
+    "decision",
+    // Self-nesting (0.17.2): a parent team contains its sub-teams / squads, one
+    // level below department_contains_team. Backs team_contains_team. Mirrors
+    // feature_area_contains_feature_area (same-type child listed last).
+    "team"
+  ],
+  // ── Data & Analytics hierarchy ───────────────────────────────────────────────
+  data_source: ["metric", "data_pipeline", "data_lineage", "event_schema"],
+  // UPG-685 T0.4 (0.13.0 Wave 1): `outcome` removed as a metric child. It closed a
+  // containment cycle (outcome ⊃ metric ⊃ outcome) and was backed only by the CAUSAL
+  // `metric_drives_outcome` edge, not a hierarchy edge — the "metric leads to outcome"
+  // meaning lives correctly on that causal edge. The real containment (outcome ⊃ metric)
+  // is kept. Sub-metric trees (metric ⊃ metric) stay.
+  metric: ["metric", "data_quality_rule", "metric_quality_assessment"],
+  data_domain: ["data_product", "data_source", "glossary_term", "data_model", "dashboard"],
+  dashboard: ["report", "experiment_run"],
+  // ── Content & Knowledge hierarchy ────────────────────────────────────────────
+  // release contains features and bugs (GitHub milestone→issue import).
+  release: ["changelog", "feature", "bug"],
+  content_strategy: ["content_calendar", "content_theme"],
+  content_calendar: [
+    "content_theme",
+    "content_piece",
+    "knowledge_base_article",
+    "brand_asset",
+    "document",
+    "documentation_template"
+  ],
+  // ── Operations & CS hierarchy ────────────────────────────────────────────────
+  service_blueprint: [
+    "user_flow",
+    "playbook",
+    "service_level_agreement",
+    "customer_health_score",
+    "support_ticket",
+    "customer_feedback"
+  ],
+  customer_health_score: ["nps_campaign", "success_milestone"],
+  customer_feedback: ["churn_reason"],
+  user_flow: ["screen", "customer_journey_stage"],
+  customer_journey_stage: ["touchpoint"],
+  // ── Legal, Compliance & Risk hierarchy ──────────────────────────────────────
+  legal_entity: ["ip_asset", "contract"],
+  contract: ["contract_clause"],
+  compliance_framework: [
+    "security_audit",
+    "compliance_requirement",
+    "privacy_policy",
+    "audit_log_policy",
+    "risk",
+    "data_contract",
+    "legal_entity"
+  ],
+  // ── DevOps & Platform hierarchy ──────────────────────────────────────────────
+  infrastructure_component: [
+    "service_level_objective",
+    "monitor",
+    "ci_pipeline",
+    "incident",
+    "runbook",
+    "release_strategy",
+    "on_call_rotation"
+  ],
+  service_level_objective: ["service_level_indicator", "error_budget"],
+  incident: ["postmortem"],
+  monitor: ["alert_rule"],
+  ci_pipeline: ["build_artifact"],
+  // ── Security hierarchy ───────────────────────────────────────────────────────
+  security_policy: [
+    "security_control",
+    "access_policy",
+    "data_classification",
+    "threat_model",
+    "security_review",
+    "incident"
+  ],
+  security_review: ["penetration_test"],
+  threat_model: ["threat", "vulnerability"],
+  // ── Sales & Revenue hierarchy ────────────────────────────────────────────────
+  pipeline_sales: ["pipeline_stage", "lead", "account", "forecast", "subscription"],
+  account: ["contact", "deal"],
+  deal: ["quote_document"],
+  subscription: ["invoice"],
+  // ── Program Management hierarchy ─────────────────────────────────────────────
+  program: ["project", "risk_register", "change_request", "resource_allocation", "status_report"],
+  project: ["milestone", "deliverable"],
+  risk_register: ["risk"],
+  // ── Accessibility hierarchy ──────────────────────────────────────────────────
+  a11y_standard: ["a11y_guideline", "a11y_audit", "a11y_annotation"],
+  a11y_audit: ["a11y_issue"],
+  // ── Product Specification expansion ─────────────────────────────────────────
+  roadmap: ["roadmap_item", "roadmap_theme", "release"],
+  roadmap_theme: ["feature"],
+  // ── Unified Context Layer hierarchy ─────────────────────────────────────────
+  design_system: [
+    "design_component",
+    "design_token",
+    "design_guideline",
+    "brand_identity",
+    "user_journey",
+    "user_flow",
+    "insight"
+  ],
+  screen: ["screen_state", "screen", "surface", "design_component", "wireframe"],
+  // self-nesting + surfaces + components + wireframes
+  // surface (0.27.0): the place inside a screen. Self-nests, so a shell holds
+  // panes, a pane holds regions, a region holds slots. A surface is reached
+  // through the screen that renders it (`screen: [... 'surface']`), never as a
+  // top-level product child: every UPG_VALID_CHILDREN pair must be backed by a
+  // hierarchy-classified edge (guardrail G2b), and the ratified ten do not
+  // include a product-to-surface verb. An app-shell surface therefore hangs off
+  // the screen that mounts it.
+  //
+  // NOTE: `surface_kind` narrows this further than UPG_VALID_CHILDREN can
+  // express. UPG_VALID_CHILDREN is keyed on entity TYPE, so it can only say
+  // "a surface may contain a surface"; the kind ordering (shell > tool > pane >
+  // region > slot / gutter / action_bar, with overlay and ambient parented by
+  // whatever raises them) is a property-level rule documented on `SurfaceKind`
+  // and enforced by validators, not by this table. Precedent: the same split
+  // applies to `planning_cycle`, whose `cadence_kind` narrows its self-nesting.
+  surface: ["surface", "design_component"],
+  // ── Marketing & Communications hierarchy ────────────────────────────────────
+  marketing_strategy: [
+    "marketing_channel",
+    "seo_keyword",
+    "press_release",
+    "event",
+    "community_initiative"
+  ],
+  marketing_channel: ["marketing_campaign_plan"],
+  marketing_campaign_plan: ["email_sequence", "social_post", "ad_creative"],
+  // ── Localisation & i18n hierarchy ───────────────────────────────────────────
+  locale: ["translation_bundle", "cultural_adaptation", "regional_pricing", "locale_config"],
+  translation_bundle: ["translation_key"],
+  // ── Customer Education & Training hierarchy ──────────────────────────────────
+  education_program: [
+    "tutorial",
+    "walkthrough",
+    "webinar",
+    "certification",
+    "help_video",
+    "learning_path"
+  ],
+  // a learning_path can include its terminal certification.
+  learning_path: ["tutorial", "certification"],
+  // ── Quality Assurance & Testing hierarchy ────────────────────────────────────
+  // (UPG-678) test_plan re-homed validation → QA. It is the QA planning layer:
+  // the verification approach (scope, environments, pass criteria) that the
+  // test suites execute. A test_plan groups the suites that carry it out.
+  test_plan: ["test_suite", "test_environment"],
+  test_suite: [
+    "test_case",
+    "regression_test",
+    "qa_session",
+    "test_coverage_report",
+    "test_environment",
+    "test_result"
+  ],
+  test_case: ["test_result"],
+  qa_session: ["bug"],
+  // ── Partner & Ecosystem Management hierarchy ─────────────────────────────────
+  partner_program: [
+    "partner_tier",
+    "integration_partner",
+    "partner_revenue_share",
+    "api_ecosystem",
+    "developer_portal"
+  ],
+  api_ecosystem: ["marketplace_listing"],
+  // ── Feedback & Voice of Customer hierarchy ───────────────────────────────────
+  feedback_program: [
+    "feature_request",
+    "nps_campaign",
+    "feedback_theme",
+    "user_advisory_board",
+    "beta_program"
+  ],
+  feature_request: ["feedback_vote"],
+  // v0.5.8 (UPG-528 Part 2d): CABs convene as quarterly ceremonies;
+  // CAB owns its meeting cadence (Stettler, Moore CAB playbook canon).
+  // Pairs with `user_advisory_board_convenes_as_ceremony` in the edge
+  // catalog. ceremony now has two valid hierarchy parents (team for sprint
+  // ceremonies, user_advisory_board for CAB meetings).
+  user_advisory_board: ["ceremony"],
+  // ── Pricing & Packaging hierarchy ────────────────────────────────────────────
+  pricing_strategy: [
+    "experiment_plan",
+    "pricing_tier",
+    "discount_strategy",
+    "trial_config",
+    "paywall"
+  ],
+  // ── AI/ML Operations hierarchy ───────────────────────────────────────────────
+  // (UPG-665) The prompt abstraction is corrected: ai_model → prompt_template →
+  // prompt_version (a model has templates; each template has versions). The
+  // model no longer owns prompt_version directly.
+  ai_model: [
+    "prompt_template",
+    "eval_benchmark",
+    "ai_cost_tracker",
+    "hallucination_report",
+    "ai_guardrail",
+    "model_comparison",
+    "ai_experiment",
+    "ai_dataset",
+    "ai_trace"
+  ],
+  // prompt_template owns its prompt_versions the way a file owns its commits.
+  prompt_template: ["prompt_version"],
+  // v0.5.7 (UPG-528 Part 2c): benchmarks define the metric set they measure
+  // (HELM, MLPerf, BIG-bench all spec a metric list). metric already has many
+  // hierarchy parents (outcome, objective, key_result, solution, data_source).
+  eval_benchmark: ["eval_run", "metric"],
+  // ai_trace spawns child traces for sub-calls (tool calls, chained
+  // prompts). Self-nesting enables call-tree representation.
+  ai_trace: ["ai_trace"],
+  // ── Agentic Workflows & Process hierarchy ────────────────────────────────────
+  workflow_template: ["workflow_run", "review_gate", "agent_task"],
+  workflow_run: ["workflow_artifact"],
+  agent_definition: ["agent_session", "agent_skill", "agent_hook", "workflow_template", "agent_task"],
+  // v0.5.8 (UPG-528 Part 2d): review gates also vet research insights
+  // (ResearchOps insight-review pattern). Pairs with `review_gate_vets_insight`
+  // in the edge catalog. The gate now owns two child types: approval records
+  // for workflow gates, insights for research-democratisation gates.
+  review_gate: ["approval_record", "insight"],
+  // ── Investigation hierarchy ──────────────────────────────────────────────────
+  investigation: ["symptom", "root_cause"],
+  root_cause: ["fix"],
+  // ── Portfolio layer hierarchy ────────────────────────────────────────────────
+  // organization → product_area is the org-axis anchor (who owns what);
+  // organization → portfolio is the strategic-axis anchor (where you invest).
+  // organization → workspace (WS3, 2026-07-05): org-altitude workspace anchor
+  // (organization_thinks_in_workspace) — a workspace scoped to org altitude
+  // lives in the same portfolio-level graph as its organization node.
+  organization: ["portfolio", "product_area", "workspace"],
+  // portfolios can nest (multi-level investment structures).
+  portfolio: ["product", "portfolio"],
+  // product_area is the organisational container for products and can
+  // nest (parent → sub-area). product_area also groups features; the
+  // "Studio area owns 6 features" mental model. product_area → workspace
+  // (WS3, 2026-07-05): plane-altitude workspace anchor
+  // (product_area_thinks_in_workspace) — "plane" is Entopo's app-level name
+  // for product_area, not a distinct spec entity.
+  product_area: ["product", "product_area", "feature", "workspace"]
+};
+function getValidChildren(entityType) {
+  return UPG_VALID_CHILDREN[entityType] ?? [];
+}
+function canBeChildOf(childType, parentType) {
+  return getValidChildren(parentType).includes(childType);
+}
+var UPG_CONTAINMENT_FREE_TYPES = /* @__PURE__ */ new Set([
   "person",
-  "department",
-  "skill",
-  "ceremony",
-  // ── Data & Analytics (4 of 10): lineage and domain containers, plus
-  //    atomic definitions ────────────────────────────────────────────────────
-  "data_lineage",
-  "data_domain",
-  "data_quality_rule",
-  // ── AI (3 of 10): traces and cost trackers are append-only; model
-  //    comparison snapshots are immutable ───────────────────────────────────
-  "ai_cost_tracker",
-  "ai_trace",
-  // ── Automation (2 of 6): approvals and artifacts are ledger entries ──────
-  "approval_record",
-  "workflow_artifact",
-  // ── Growth (7 of 9): funnels and attribution are structural definitions;
-  //    cohorts/segments are computed snapshots ────────────────────────────
-  "funnel",
-  "funnel_step",
-  "acquisition_channel",
-  "cohort",
-  "behavioral_segment",
-  "growth_loop",
-  "attribution_model",
-  // ── Sales (5 of 6): pipeline structure + accounts/contacts + forecast
-  //    snapshots. Only `deal` has a lifecycle (Phase B SALES_DEAL template) ─
-  "account",
-  "contact",
-  "pipeline_sales",
-  "pipeline_stage",
-  "forecast",
-  // ── Customer Success (5 of 9): journey structure + derived values ────────
-  "customer_journey_stage",
-  "touchpoint",
-  "churn_reason",
-  "service_level_agreement",
-  // ── DevOps (5 of 10): indicators and budgets are measurement references;
-  //    strategies and pipelines are configuration ──────────────────────────
-  "service_level_indicator",
-  "service_level_objective",
-  "error_budget",
-  "ci_pipeline",
-  "release_strategy",
-  // ── Security (1 of 5): data classification is a reference label ──────────
-  "data_classification",
-  // ── Accessibility (2 of 4): standards and annotations ─────────────────────
-  "a11y_standard",
-  "a11y_annotation",
-  // ── Testing (3 of 5): regression tests are reference definitions; test
-  //    results and coverage reports are immutable records ───────────────────
-  "regression_test",
-  "test_coverage_report",
-  "test_result",
-  // ── Customer Feedback (2 of 3): themes and votes are atomic data points ──
-  "feedback_theme",
-  "feedback_vote",
-  // ── Pricing (2 of 4): trial and paywall are configuration ─────────────────
-  "trial_config",
-  "paywall",
-  // ── Content (2 of 5): calendars and themes are planning configuration ────
-  "content_calendar",
-  "content_theme",
-  // ── Legal (2 of 3): legal_entity is an org; contract_clause is an atom
-  //    of a contract (which has its own lifecycle) ───────────────────────────
-  "legal_entity",
-  "contract_clause",
-  // ── Portfolio (3 of 3): structural containers ─────────────────────────────
-  "organization",
-  "portfolio",
-  "product_area",
-  // ── Program Management (2 of 3): allocations and registers are tracking
-  //    containers ────────────────────────────────────────────────────────────
-  "resource_allocation",
-  "risk_register",
-  // ── Localisation (4 of 5): translation keys, configs, and regional
-  //    adaptations are reference data ────────────────────────────────────────
-  "translation_key",
-  "locale_config",
-  "cultural_adaptation",
-  "regional_pricing",
-  // ── Marketing (1 of 4): SEO keywords are tracked reference terms ─────────
-  "seo_keyword",
-  // ── Ecosystem (2 of 2): partner tiers and rev-share terms are config ─────
-  "partner_tier",
-  "partner_revenue_share",
-  // ── Validation (2 of 4): evidence + learning are data points captured
-  //    from experiment_runs (which have lifecycles); hypothesis_evidence was
-  //    lifecycle-free here but is deprecated at v0.4.0 ──────────────────────────────────────
-  "evidence",
-  "learning",
-  // ── Workspace (1 of 4): a capture is a fact about a moment, not a workflow.
-  //    It is taken, and from then on it either still matches its subject or it
-  //    does not — which is what `content_hash` answers, not a phase. ─────────
+  // A framework_exercise has no structural parent: it anchors to the entities
+  // it scores via the `framework_exercise_includes_node` edge, not by
+  // 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",
+  // 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",
+  // A capture has no structural parent for the same reason: it anchors to what
+  // it RENDERS, via `capture_renders_node`. Giving it a product parent would
+  // claim a capture is part of the product rather than a picture of one, and
+  // would mint a containment edge whose only job is to satisfy the hierarchy.
   "capture"
 ]);
-function isLifecycleFreeType(entityType) {
-  return UPG_LIFECYCLE_FREE_TYPES.has(entityType);
+function isContainmentFreeType(entityType) {
+  return UPG_CONTAINMENT_FREE_TYPES.has(entityType);
 }
-var UPG_LIFECYCLE_PLANNED_TYPES = /* @__PURE__ */ new Set([
-  // Phase B cleared this set entirely. Every type that was triaged
-  // into Phase B/C/D under now either has a lifecycle in
-  // `UPG_LIFECYCLES` or is documented as lifecycle-free in
-  // `UPG_LIFECYCLE_FREE_TYPES`.
-  //
-  // Reintroduce entries here when a new entity type is added to the spec
-  // and decided to be lifecycle-bearing but its phases have not yet been
-  // designed. The `10-lifecycle-coverage` audit will surface uncovered
-  // active types until they're either implemented or moved to the
-  // free-types set.
-]);
-function isLifecyclePlannedType(entityType) {
-  return UPG_LIFECYCLE_PLANNED_TYPES.has(entityType);
+
+// src/grammar/projection.ts
+var VARIES_BY_EDGE = "surface_varies_by_configuration_axis";
+var PRESENT_UNDER_PROPERTY = "present_under";
+var ACTIVE_WHEN_PROPERTY = "active_when";
+var QUALIFIABLE_EDGE_TYPES = [
+  "surface_contains_surface",
+  "feature_occupies_surface"
+];
+function readStringArray(properties, key) {
+  const raw = properties?.[key];
+  if (!Array.isArray(raw)) return void 0;
+  return raw.filter((v) => typeof v === "string");
 }
-function getLifecycleRenderShape(entityType) {
-  const lifecycle = getLifecycleForType(entityType);
-  if (!lifecycle) return null;
-  const terminalSet = new Set(lifecycle.terminal_phases);
-  const phaseIndex = new Map(lifecycle.phases.map((p, i) => [p.id, i]));
-  const states = lifecycle.phases.map((phase) => ({
-    id: phase.id,
-    label: phase.label,
-    description: phase.description,
-    terminal: terminalSet.has(phase.id)
-  }));
-  const transitions = [];
-  for (const phase of lifecycle.phases) {
-    const fromTerminal = terminalSet.has(phase.id);
-    for (const to of phase.transitions_to) {
-      const toTerminal = terminalSet.has(to);
-      let kind;
-      if (fromTerminal && !toTerminal) {
-        kind = "reopen";
-      } else if (toTerminal && !fromTerminal) {
-        kind = "terminal";
-      } else {
-        const fromIdx = phaseIndex.get(phase.id) ?? 0;
-        const toIdx = phaseIndex.get(to) ?? 0;
-        kind = toIdx < fromIdx ? "backward" : "forward";
+function readActiveWhen(edge) {
+  const raw = edge.properties?.[ACTIVE_WHEN_PROPERTY];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const axis = raw.axis;
+  const values = readStringArray(raw, "values");
+  if (typeof axis !== "string" || axis.length === 0 || !values || values.length === 0) {
+    return void 0;
+  }
+  return { axis, values };
+}
+function projectGraph(nodes, edges, configuration) {
+  const axes = Object.keys(configuration);
+  if (axes.length === 0) {
+    return {
+      nodes: [...nodes],
+      edges: [...edges],
+      excluded_node_ids: [],
+      deactivated_edge_count: 0,
+      dangling_edge_count: 0
+    };
+  }
+  const excluded = /* @__PURE__ */ new Set();
+  for (const edge of edges) {
+    if (edge.type !== VARIES_BY_EDGE) continue;
+    const chosen = configuration[edge.target];
+    if (chosen === void 0) continue;
+    const presentUnder = readStringArray(edge.properties, PRESENT_UNDER_PROPERTY);
+    if (!presentUnder) continue;
+    if (!presentUnder.includes(chosen)) excluded.add(edge.source);
+  }
+  const survivingNodes = excluded.size === 0 ? [...nodes] : nodes.filter((n) => !excluded.has(n.id));
+  let deactivated = 0;
+  let dangling = 0;
+  const survivingEdges = [];
+  for (const edge of edges) {
+    const qualifier = readActiveWhen(edge);
+    if (qualifier) {
+      const chosen = configuration[qualifier.axis];
+      if (chosen !== void 0 && !qualifier.values.includes(chosen)) {
+        deactivated++;
+        continue;
       }
-      transitions.push({ from: phase.id, to, kind });
     }
+    if (excluded.has(edge.source) || excluded.has(edge.target)) {
+      dangling++;
+      continue;
+    }
+    survivingEdges.push(edge);
   }
   return {
-    entity_type: lifecycle.entity_type,
-    ...lifecycle.template_id !== void 0 && { template_id: lifecycle.template_id },
-    states,
-    transitions,
-    initial_state: lifecycle.initial_phase
+    nodes: survivingNodes,
+    edges: survivingEdges,
+    excluded_node_ids: [...excluded].sort(),
+    deactivated_edge_count: deactivated,
+    dangling_edge_count: dangling
   };
 }
+function enumerateProjections(nodes) {
+  const out = [
+    { configuration: {} }
+  ];
+  for (const node of nodes) {
+    if (node.type !== "configuration_axis") continue;
+    const values = readStringArray(node.properties, "values");
+    if (!values) continue;
+    for (const value of values) {
+      out.push({ axis: node.id, value, configuration: { [node.id]: value } });
+    }
+  }
+  return out;
+}
+
+// src/grammar/configuration-drift.ts
+var ALTERNATES_EDGE = "surface_alternates_with_surface";
+var PARENT_EDGE_TYPES = /* @__PURE__ */ new Set(["surface_contains_surface", "screen_renders_surface"]);
+function edgeLabel(edge) {
+  return edge.id ?? `${edge.source} -> ${edge.target}`;
+}
+function checkConfigurationDrift(nodes, edges) {
+  const findings = [];
+  const axisValues = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    if (node.type !== "configuration_axis") continue;
+    const values = readStringArray(node.properties, "values");
+    if (!values || values.length === 0) {
+      findings.push({
+        kind: "axis_values_empty",
+        severity: "error",
+        node_id: node.id,
+        axis_id: node.id,
+        message: "Configuration axis declares no values. An axis with no values selects nothing, so no projection can be taken along it."
+      });
+      axisValues.set(node.id, []);
+      continue;
+    }
+    axisValues.set(node.id, values);
+    const rawDefault = node.properties?.default_value;
+    if (typeof rawDefault === "string" && rawDefault.length > 0 && !values.includes(rawDefault)) {
+      findings.push({
+        kind: "axis_default_not_a_value",
+        severity: "error",
+        node_id: node.id,
+        axis_id: node.id,
+        message: `default_value "${rawDefault}" is not one of the axis values [${values.join(", ")}]. It names a value of this axis, so it has to be one the axis declares.`
+      });
+    }
+  }
+  for (const edge of edges) {
+    if (edge.type !== VARIES_BY_EDGE) continue;
+    const values = axisValues.get(edge.target);
+    const presentUnder = readStringArray(edge.properties, PRESENT_UNDER_PROPERTY);
+    if (!presentUnder || presentUnder.length === 0) {
+      findings.push({
+        kind: "present_under_empty",
+        severity: "error",
+        edge_id: edge.id,
+        node_id: edge.source,
+        axis_id: edge.target,
+        message: `${edgeLabel(edge)} declares variance without a non-empty present_under. A surface that exists under no configuration should be deleted rather than declared; a surface that exists under all of them should carry no varies_by edge at all.`
+      });
+      continue;
+    }
+    if (!values) continue;
+    for (const value of presentUnder) {
+      if (!values.includes(value)) {
+        findings.push({
+          kind: "present_under_unknown_value",
+          severity: "error",
+          edge_id: edge.id,
+          node_id: edge.source,
+          axis_id: edge.target,
+          message: `present_under names "${value}", which the axis does not declare. Its values are [${values.join(", ")}].`
+        });
+      }
+    }
+  }
+  for (const edge of edges) {
+    const hasQualifierKey = edge.properties !== void 0 && Object.prototype.hasOwnProperty.call(edge.properties, ACTIVE_WHEN_PROPERTY);
+    if (!hasQualifierKey) continue;
+    if (edge.type !== void 0 && !QUALIFIABLE_EDGE_TYPES.includes(edge.type)) {
+      findings.push({
+        kind: "qualifier_on_illegal_edge",
+        severity: "error",
+        edge_id: edge.id,
+        message: `active_when is not legal on ${edge.type}. The qualifier is scoped to [${QUALIFIABLE_EDGE_TYPES.join(", ")}] deliberately: conditional composition is the question this release answers, and a general modality system is not.`
+      });
+      continue;
+    }
+    const qualifier = readActiveWhen(edge);
+    if (!qualifier) {
+      const rawQualifier = edge.properties?.[ACTIVE_WHEN_PROPERTY];
+      const rawValues = rawQualifier && typeof rawQualifier === "object" && !Array.isArray(rawQualifier) ? rawQualifier.values : void 0;
+      if (Array.isArray(rawValues) && rawValues.length === 0) {
+        findings.push({
+          kind: "qualifier_values_empty",
+          severity: "error",
+          edge_id: edge.id,
+          message: `${edgeLabel(edge)} carries an active_when with an empty values list. Read literally that would remove the relationship from every configuration, which is a way to delete an edge by writing a property; it is treated as absent instead. To say a relationship never holds, delete the edge.`
+        });
+        continue;
+      }
+      findings.push({
+        kind: "qualifier_axis_unresolved",
+        severity: "error",
+        edge_id: edge.id,
+        message: `${edgeLabel(edge)} carries a malformed active_when. It must be an object with an axis id and a non-empty values array; anything else reads as absent, which silently makes the relationship invariant.`
+      });
+      continue;
+    }
+    const values = axisValues.get(qualifier.axis);
+    if (!values) {
+      findings.push({
+        kind: "qualifier_axis_unresolved",
+        severity: "error",
+        edge_id: edge.id,
+        axis_id: qualifier.axis,
+        message: `active_when names axis "${qualifier.axis}", which is not a configuration_axis node in this graph.`
+      });
+      continue;
+    }
+    for (const value of qualifier.values) {
+      if (!values.includes(value)) {
+        findings.push({
+          kind: "qualifier_unknown_value",
+          severity: "error",
+          edge_id: edge.id,
+          axis_id: qualifier.axis,
+          message: `active_when names value "${value}", which axis "${qualifier.axis}" does not declare. Its values are [${values.join(", ")}].`
+        });
+      }
+    }
+  }
+  const varianceBySource = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    if (edge.type !== VARIES_BY_EDGE) continue;
+    const values = readStringArray(edge.properties, PRESENT_UNDER_PROPERTY) ?? [];
+    const list = varianceBySource.get(edge.source) ?? [];
+    list.push({ axis: edge.target, values });
+    varianceBySource.set(edge.source, list);
+  }
+  for (const edge of edges) {
+    if (edge.type !== ALTERNATES_EDGE) continue;
+    const left = varianceBySource.get(edge.source) ?? [];
+    const right = varianceBySource.get(edge.target) ?? [];
+    if (left.length === 0 || right.length === 0) {
+      findings.push({
+        kind: "alternation_axis_mismatch",
+        severity: "error",
+        edge_id: edge.id,
+        message: `${edgeLabel(edge)} declares an alternation, but at least one endpoint declares no variance at all. Two surfaces that are both always present are not alternatives; they co-exist.`
+      });
+      continue;
+    }
+    const sharedAxes = left.filter((l) => right.some((r) => r.axis === l.axis)).map((l) => l.axis);
+    if (sharedAxes.length === 0) {
+      findings.push({
+        kind: "alternation_axis_mismatch",
+        severity: "error",
+        edge_id: edge.id,
+        message: `${edgeLabel(edge)} declares an alternation between surfaces that vary on different axes. Alternatives are selected by ONE lever; surfaces on different levers can both be present at once.`
+      });
+      continue;
+    }
+    for (const axis of sharedAxes) {
+      const leftValues = left.find((l) => l.axis === axis)?.values ?? [];
+      const rightValues = right.find((r) => r.axis === axis)?.values ?? [];
+      const overlap = leftValues.filter((v) => rightValues.includes(v));
+      if (overlap.length > 0) {
+        findings.push({
+          kind: "alternation_overlap",
+          severity: "error",
+          edge_id: edge.id,
+          axis_id: axis,
+          message: `${edgeLabel(edge)} declares an alternation, but both surfaces are present under [${overlap.join(", ")}] on axis "${axis}". They co-exist there, so the graph is asserting "one of these" and "both, together" about the same pair.`
+        });
+      }
+    }
+  }
+  const parentsByChild = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    if (edge.type && PARENT_EDGE_TYPES.has(edge.type)) {
+      parentsByChild.set(edge.target, (parentsByChild.get(edge.target) ?? 0) + 1);
+    }
+  }
+  for (const [axisId, values] of axisValues) {
+    for (const value of values) {
+      const projected = projectGraph(nodes, edges, { [axisId]: value });
+      const survivingParents = /* @__PURE__ */ new Map();
+      for (const edge of projected.edges) {
+        if (edge.type && PARENT_EDGE_TYPES.has(edge.type)) {
+          survivingParents.set(edge.target, (survivingParents.get(edge.target) ?? 0) + 1);
+        }
+      }
+      for (const node of projected.nodes) {
+        if (node.type !== "surface") continue;
+        if ((parentsByChild.get(node.id) ?? 0) === 0) continue;
+        if ((survivingParents.get(node.id) ?? 0) > 0) continue;
+        findings.push({
+          kind: "orphaned_under_projection",
+          severity: "warning",
+          node_id: node.id,
+          axis_id: axisId,
+          message: `Surface is present under ${axisId} = "${value}" but every containment parent it has is absent there. Either it needs a parent in that configuration, or it should declare that it is absent from it too.`
+        });
+      }
+    }
+  }
+  return findings;
+}
 
 // src/grammar/scales.ts
 var UPG_SCALES = {
@@ -11966,8 +12109,8 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // CompositionProperties
   composition: {
-    member_query: { type: "object", description: "When present, membership is DERIVED: members are produced by running this query rather than authored by placement.", notes: "This is the portable statement of what the layer shows. On a composition, `CompositionMember.href` remains the publishing tool's own resolved route and stays opaque to everyone else; a member may carry both, and then the href is a fast path while the query is the meaning. A consumer that cannot parse the href can still render the layer, which is the whole reason the declaration is here rather than in a tool-namespaced bag key. A layer with no `member_query` is authored, which is what every composition written before 0.32.0 is. DECLARED ON BOTH HALVES OF THE PAIR since 0.33.0. A layer is query-driven while it is being worked on, not only once it is published, so declaring the query only on the durable composition would make it a fact invented at publish time rather than one recorded." },
-    presentation: { type: "object", description: "Advisory rendering intent for the layer as a whole. A consumer may ignore it entirely and still be conformant." },
+    member_query: { type: "object", description: "When present, membership is DERIVED: members are produced by running this query rather than authored by placement. The clause list is authoritative and the named fields are a positive-only projection of it; since 0.34.0 a clause is a discriminated union on `dimension`, so the `type` axis carries entity types rather than free strings.", notes: "This is the portable statement of what the layer shows. On a composition, `CompositionMember.href` remains the publishing tool's own resolved route and stays opaque to everyone else; a member may carry both, and then the href is a fast path while the query is the meaning. A consumer that cannot parse the href can still render the layer, which is the whole reason the declaration is here rather than in a tool-namespaced bag key. A layer with no `member_query` is authored, which is what every composition written before 0.32.0 is. DECLARED ON BOTH HALVES OF THE PAIR since 0.33.0. A layer is query-driven while it is being worked on, not only once it is published, so declaring the query only on the durable composition would make it a fact invented at publish time rather than one recorded." },
+    presentation: { type: "object", description: "Advisory rendering intent for the layer as a whole: `group_by`, `sort`, `layout`, `nest_by`, and `orphan_disposition` (0.34.0, absent means `'root'`). A consumer may ignore it entirely and still be conformant, because every default it then applies is the safe one.", notes: "THE DESCRIPTION LISTS THE FIELDS ON PURPOSE. This property is `object` in the runtime property registry, so an agent reading `get_entity_schema` gets an opaque blob and this sentence. For an object-typed property the description IS the declared shape, which is why `check:editorial` hashes it (E.4, 0.34.0) and why a field added to `UPGViewPresentation` without a word here would be invisible to every gate and every agent at once." },
     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." },
@@ -14218,7 +14361,7 @@ var UPG_PROPERTY_SCHEMA = {
     team_type: { type: "string", enum: ["product", "engineering", "design", "growth", "customer_success"], description: "Functional area of the team" },
     size: { type: "number", description: "Number of people on the team" },
     mission: { type: "string", description: "Team's mission statement" },
-    key_prefix: { type: "string", description: 'Prefix this team mints node keys with (e.g. `"ENTP"`, giving `ENTP-1`, `ENTP-2`, ...). @example "ENTP"', notes: "SUPERSEDES `product.key_prefix` FOR THIS PRODUCT. The moment any team declares a prefix, the product-level prefix stops being consulted and the declared team prefixes become the candidate set a create surface offers. A product-level prefix that still resolved would win on order alone, and a multi-team product would then silently mint everything under it, which is the defect this field exists to end. A DECLARED PREFIX IS A CANDIDATE BEFORE IT IS OBSERVED. Candidates derived only from keys that already exist cannot see a team's first create, which is the one that most needs asking about. UNIQUENESS IS PRODUCT-SCOPED, AND A TEAM PREFIX DOES NOT WIDEN IT. The key sequence runs per product across entity types, so two teams in one product share one number line and never collide with each other. A team prefix names a team WITHIN that scope; it does not create a sequence that spans products. MINTING IS PRODUCT-SCOPED (normative, 0.33.0). `team` is `portfolio_shared`, so one team node can be referenced from two products. Minting is not portfolio-scoped with it. The rule, and it is a requirement rather than a recommendation: 1. A portfolio-shared team's prefix is NOT a minting candidate in a second product. The first product a team mints under is the only product that prefix mints in. 2. Refusal is NO-KEY. The node is created without a key. Refusal MUST NOT be an exception: a keyless create is a legal outcome everywhere else in the ladder, and throwing here would break creates that succeed today on every surface. Throwing stays reserved for a broken invariant, not for policy. 3. The rule applies on the MINT path, not the picker path, and it covers the INFERRED case. A prefix that was never requested by anyone, and was derived from keys that already exist in the second product, is refused on the same terms as one a caller named. A guard that only inspects an explicitly requested prefix misses the quiet path, and the quiet path is the one a fixture reproduces. WHY THE SCOPE STOPS AT THE PRODUCT. Key uniqueness is enforced by a `(product_id, key)` index, which permits the same key under two product ids by construction. A prefix that minted in two products would therefore run two independent sequences under one name and hand two different nodes the same citation, with nothing objecting. Portfolio-shared team minting is DEFERRED until a supra-product uniqueness design exists, rather than approximated. This rule states the CONTRACT. The behaviour belongs to whatever mints keys, which is not this package: see `UPGBaseNode.key`." }
+    key_prefix: { type: "string", description: 'Prefix this team mints node keys with (e.g. `"ENTP"`, giving `ENTP-1`, `ENTP-2`, ...). @example "ENTP"', notes: "SUPERSEDES `product.key_prefix` FOR THIS PRODUCT, AND NOTHING ELSE (normative, narrowed in 0.34.0). The moment any team declares a prefix, the PRODUCT-LEVEL prefix stops being consulted. A product-level prefix that still resolved would win on order alone, and a multi-team product would then silently mint everything under it, which is the defect this field exists to end. THE CANDIDATE SET IS THE UNION OF DECLARED AND OBSERVED PREFIXES. A declaration adds a candidate; it does not remove one. A prefix stops being offered only when something claims it or when nothing has ever minted under it, and while more than one candidate stands the create surface keeps asking. WHY THIS WAS NARROWED, stated because 0.33.0 shipped the wider reading and an implementer built against it. The paragraph above made ANY declaration replace the candidate set outright, and its own stated rationale is entirely about `product.key_prefix`: a SINGLE STRING, declared once, that cannot represent two teams. An OBSERVED prefix is not that. It is evidence of a namespace already in active use. Suppressing it reproduces the precise defect this field exists to end, inside one product, and does so silently. Measured on the only keyed graph in the estate: it carries two observed prefixes, 370 keys under one and 662 under the other, and declares neither. Under the wider reading, one team declaring the smaller prefix collapses the candidate set to it, the picker disappears, and every later create mints under it, including the 662 keys' worth of work belonging to the other namespace. The sentence over-reached beyond its own reason, and this narrows it back to that reason. Shipped as a CHANGE in 0.34.0 rather than as a patch correction. Read as a correction it is defensible, but implementers had already built to the wider text, and moving a contract under them in a patch is how a patch becomes a surprise. A DECLARED PREFIX IS A CANDIDATE BEFORE IT IS OBSERVED. Candidates derived only from keys that already exist cannot see a team's first create, which is the one that most needs asking about. That is why declaration ADDS to the candidate set; it is not a reason for it to subtract. UNIQUENESS IS PRODUCT-SCOPED, AND A TEAM PREFIX DOES NOT WIDEN IT. The key sequence runs per product across entity types, so two teams in one product share one number line and never collide with each other. A team prefix names a team WITHIN that scope; it does not create a sequence that spans products. MINTING IS PRODUCT-SCOPED (normative, 0.33.0). `team` is `portfolio_shared`, so one team node can be referenced from two products. Minting is not portfolio-scoped with it. The rule, and it is a requirement rather than a recommendation: 1. A portfolio-shared team's prefix is NOT a minting candidate in a second product. The first product a team mints under is the only product that prefix mints in. 2. Refusal is NO-KEY. The node is created without a key. Refusal MUST NOT be an exception: a keyless create is a legal outcome everywhere else in the ladder, and throwing here would break creates that succeed today on every surface. Throwing stays reserved for a broken invariant, not for policy. 3. The rule applies on the MINT path, not the picker path, and it covers the INFERRED case. A prefix that was never requested by anyone, and was derived from keys that already exist in the second product, is refused on the same terms as one a caller named. A guard that only inspects an explicitly requested prefix misses the quiet path, and the quiet path is the one a fixture reproduces. WHY THE SCOPE STOPS AT THE PRODUCT. Key uniqueness is enforced by a `(product_id, key)` index, which permits the same key under two product ids by construction. A prefix that minted in two products would therefore run two independent sequences under one name and hand two different nodes the same citation, with nothing objecting. Portfolio-shared team minting is DEFERRED until a supra-product uniqueness design exists, rather than approximated. HOW RULE 1 IS DECIDED: THE EVIDENCE RULE (normative, 0.34.0). Rule 1 names a first product without saying how a minter knows which one it is. It is decided by EVIDENCE, not by a stored marker: at mint, if any other IN-SCOPE product already holds a key under the prefix, refuse. Evidence is derivable from the graphs themselves, needs no migration, cannot go stale, and cannot disagree with the keys. A durable home marker could do all three, and would mint state for a fact the graph already carries. The cost is stated rather than hidden: evidence is SCOPE-DEPENDENT, which is why the scope is ruled below in the same breath rather than left open. THE UNDECIDABLE CASE: NEITHER MINTS (normative, 0.34.0). When two products already hold keys under one prefix and nothing establishes which was first, NEITHER mints. No tiebreak is invented. Creation order is not recorded, and `max(existing)` measures import volume rather than precedence, so any tiebreak would be a guess wearing a rule, and a silent one, since it would attribute a namespace to a product with nothing to say it was wrong. Refusing both is the NO-KEY outcome rule 2 already sanctions, and it is recoverable: once either product declares the prefix, the other is unambiguous and a backfill can run. WHAT \"IN SCOPE\" MEANS: ENGINE-DEFINED, WITH A FLOOR AND A CEILING (normative, 0.34.0). The scope over which the evidence rule looks is defined by the engine, bounded on both sides. FLOOR. It MUST include every product the engine can enumerate for this caller. An engine that looks at fewer products than it can see is choosing not to notice a collision it could have seen. CEILING. It MUST NEVER include a product the caller could not otherwise read. A wider read is a cross-tenant information channel: refusing a mint because of a key in a graph the caller cannot see leaks that the graph exists and what is in it. This half is a security constraint and is not negotiable. PORTFOLIO ALTITUDE IS THE WRONG NORMATIVE ALTITUDE, and it was measured rather than argued: deleting the portfolio document changes nothing about minting, because no minter consults the portfolio seam. Stating the invariant there states it where nobody looks. In practice the local engine's scope is every graph in the workspace folder and the cloud engine's is the caller's own product list. THE HONEST CONSEQUENCE, which belongs in the text rather than in a later surprise: the invariant is SCOPE-RELATIVE. Two engines can legitimately disagree about whether one mint is safe, because they can legitimately see different sets of products. That is a real limitation of the evidence rule and the price of the ceiling. IMMUTABLE ONCE ANYTHING HAS MINTED UNDER IT, PER PRODUCT (normative, 0.34.0). Once any key exists under this prefix IN A GIVEN PRODUCT, the declaration cannot be edited for that product. Refusal-shaped and NO-KEY, matching rule 2: never an exception, because a keyless create is legal everywhere else in the ladder. SCOPED PER PRODUCT, NOT PER TEAM, and the reason is that `team` is `portfolio_shared`: a team that has never minted in product B must still be free to declare there. A per-team global lock would strand it. WHAT IT PREVENTS. Without it, a team edits its prefix after four hundred mints and one product silently carries two number lines under two names, with nothing recording that they were ever one sequence. RENAMING STAYS POSSIBLE BY THE HONEST ROUTE: a migration that rewrites the existing keys. That is a deliberate act with a visible cost, which is the difference between renaming a namespace and forking it by accident. THE PICKER MAY OFFER WHAT THE MINT REFUSES, AND THE SURFACE OWNS THE DIVERGENCE (0.34.0). Rule 3 applies on the MINT path and not the picker path, which is deliberate: the picker cannot cheaply know the answer, since knowing it requires reading other products. The consequence is that a surface can present a choice that then fails. The owner is named here rather than left implicit: A CREATE SURFACE THAT OFFERS A PREFIX THE MINT MAY REFUSE MUST BE ABLE TO REPORT THE REFUSAL, AND MUST BE ABLE TO PRESENT NO-KEY AS AN OUTCOME RATHER THAN AS AN ERROR. This is a design obligation on the surface, not a spec mechanic: the spec cannot fix a UX gap and should not pretend to. The union ruling above shrinks the divergence considerably, because the picker now keeps asking in exactly the case that would otherwise resolve wrongly. This rule states the CONTRACT. The behaviour belongs to whatever mints keys, which is not this package: see `UPGBaseNode.key`." }
   },
   // TeamOkrProperties: TeamOkr entity.
   team_okr: {
@@ -14544,8 +14687,8 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // WorkspaceProperties: Workspace: a spatial thinking space for arranging entities.
   workspace: {
-    member_query: { type: "object", description: "When present, membership is DERIVED: members are produced by running this query rather than authored by placement.", notes: "This is the portable statement of what the layer shows. On a composition, `CompositionMember.href` remains the publishing tool's own resolved route and stays opaque to everyone else; a member may carry both, and then the href is a fast path while the query is the meaning. A consumer that cannot parse the href can still render the layer, which is the whole reason the declaration is here rather than in a tool-namespaced bag key. A layer with no `member_query` is authored, which is what every composition written before 0.32.0 is. DECLARED ON BOTH HALVES OF THE PAIR since 0.33.0. A layer is query-driven while it is being worked on, not only once it is published, so declaring the query only on the durable composition would make it a fact invented at publish time rather than one recorded." },
-    presentation: { type: "object", description: "Advisory rendering intent for the layer as a whole. A consumer may ignore it entirely and still be conformant." },
+    member_query: { type: "object", description: "When present, membership is DERIVED: members are produced by running this query rather than authored by placement. The clause list is authoritative and the named fields are a positive-only projection of it; since 0.34.0 a clause is a discriminated union on `dimension`, so the `type` axis carries entity types rather than free strings.", notes: "This is the portable statement of what the layer shows. On a composition, `CompositionMember.href` remains the publishing tool's own resolved route and stays opaque to everyone else; a member may carry both, and then the href is a fast path while the query is the meaning. A consumer that cannot parse the href can still render the layer, which is the whole reason the declaration is here rather than in a tool-namespaced bag key. A layer with no `member_query` is authored, which is what every composition written before 0.32.0 is. DECLARED ON BOTH HALVES OF THE PAIR since 0.33.0. A layer is query-driven while it is being worked on, not only once it is published, so declaring the query only on the durable composition would make it a fact invented at publish time rather than one recorded." },
+    presentation: { type: "object", description: "Advisory rendering intent for the layer as a whole: `group_by`, `sort`, `layout`, `nest_by`, and `orphan_disposition` (0.34.0, absent means `'root'`). A consumer may ignore it entirely and still be conformant, because every default it then applies is the safe one.", notes: "THE DESCRIPTION LISTS THE FIELDS ON PURPOSE. This property is `object` in the runtime property registry, so an agent reading `get_entity_schema` gets an opaque blob and this sentence. For an object-typed property the description IS the declared shape, which is why `check:editorial` hashes it (E.4, 0.34.0) and why a field added to `UPGViewPresentation` without a word here would be invisible to every gate and every agent at once." },
     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: "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." },
@@ -29013,6 +29156,48 @@ var UPG_ANTI_PATTERNS = [
     severity: "medium",
     source: { kind: "fundamental" }
   },
+  // ── Citable-key collision (0.34.0): portfolio-scoped, and the FIRST detector
+  // to ship with a labeled corpus behind it (packages/upg-evals/corpora/
+  // intelligence/duplicate-key-across-products/).
+  //
+  // WHY IT CANNOT BE A SINGLE-GRAPH CHECK. Key uniqueness is enforced by a
+  // `(product_id, key)` index, so each product reports its own key as valid. The
+  // collision is only visible from above, which is why this is `scope: 'portfolio'`
+  // and carries no structured_condition: the detector reads across products, and
+  // IntelligenceCondition composes aggregate counts within one graph.
+  //
+  // MECHANICALLY DECIDABLE, which is unusual in this file and is why it can ship
+  // enforced: one `(prefix, number)` pair appearing in two products of one
+  // portfolio, with no judgement about intent. Every other portfolio entry here
+  // approximates a per-node rule; this one is exact.
+  //
+  // ENFORCED FROM DAY ONE. What was staged is the CORPUS, not the enforcement.
+  // The tempting shape was a check that ships "defined" and becomes "enforced"
+  // later, and there is no such mechanic: a registered detector that declines to
+  // fire is worse than either real option, and nothing in the spec could hang it.
+  // The detector has little to fire on until a second keyed product exists, and
+  // that is a property of the estate rather than of the check.
+  //
+  // THE NEAR-MISSES ARE CONSTRUCTED, and the corpus says so in its own README
+  // rather than in a plan nobody opens. Three classes: two products sharing a
+  // prefix over DISJOINT number ranges (latent, not yet colliding); a
+  // DELIBERATELY shared prefix across a product family wanting one citation
+  // namespace; and a product holding IMPORTED keys minted elsewhere. Until a real
+  // collision is sampled, the recall figure is a claim about the author's
+  // imagination. The corpus carries a dated obligation to re-grade precision and
+  // recall on the first sampled collision.
+  {
+    id: "duplicate-key-across-products",
+    since: "0.34.0",
+    scope: "portfolio",
+    name: "One citable key, two products",
+    description: "The same (prefix, number) pair identifies a node in two or more products of one portfolio. Keys are minted per product and uniqueness is enforced by a (product_id, key) index, so two products minting under one prefix run two independent sequences under one name. Each product reports its own key as valid and only the portfolio can see that the citation is ambiguous.",
+    why_it_matters: "A key exists to be cited. When one citation resolves to two different things, every reference made with it becomes ambiguous after the fact, including references already written down outside the graph where nothing can be corrected. The damage is retroactive and grows with adoption: the longer both sequences run, the more citations a reconciliation has to rewrite.",
+    remediation: "Decide which product owns the prefix and declare it there with team.key_prefix, so ownership is explicit rather than inferred. Migrate the other product by rewriting its existing keys, which is deliberate and visibly costly, never by editing a declaration under a live sequence. If both products want one namespace, record that decision so it does not read as drift.",
+    stages: ["build", "beta", "launch", "growth", "mature"],
+    severity: "high",
+    source: { kind: "fundamental" }
+  },
   // ── surface (0.27.0): the place, its guest list, and its arbitration rule ──
   // Three patterns, calibrated so the contention one leads and the two coverage
   // companions sit a tier below it. Like every entry in this file, each detector
@@ -32757,8 +32942,8 @@ var NODE_KEY_ORDER = [
   "sort_order",
   "properties"
 ];
-var EDGE_KEY_ORDER = ["id", "source", "target", "type", "mapping_confidence", "properties"];
-var CROSS_EDGE_KEY_ORDER = ["id", "source", "target", "type", "source_product_id", "target_product_id", "mapping_confidence", "alias", "relevance", "audience_role"];
+var EDGE_KEY_ORDER = ["id", "source", "target", "type", "mapping_confidence", "provenance", "properties"];
+var CROSS_EDGE_KEY_ORDER = ["id", "source", "target", "type", "source_product_id", "target_product_id", "mapping_confidence", "properties", "alias", "relevance", "audience_role"];
 var PRODUCT_KEY_ORDER = ["id", "title", "description", "stage", "properties"];
 function canonicalNode(node) {
   const repaired = repairNodeDrift(node);
@@ -32775,7 +32960,14 @@ function canonicalEdge(edge) {
 }
 function canonicalCrossEdge(edge) {
   return orderedObject(edge, CROSS_EDGE_KEY_ORDER, {
-    forceKeys: ["id", "source", "target", "type"]
+    forceKeys: ["id", "source", "target", "type"],
+    // `properties` is an OPEN bag and must be canonicalised like every other one
+    // (node, edge, product all pass it). Without this, two writers emitting the
+    // same parity assessment with their keys in a different order produce
+    // different bytes, which breaks contract 3 of this format: input key order
+    // does not change the output. Free to fix today and measured as such: zero
+    // of the 61 cross-edges in the estate carry properties.
+    openKeys: ["properties"]
   });
 }
 function canonicalProduct(product) {
@@ -33036,7 +33228,7 @@ function checkHeaderSealText(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.33.0";
+var UPG_VERSION = "0.34.0";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -33099,6 +33291,14 @@ var UPG_ENTITY_COUNT = UPG_TYPES.length;
 var UPG_DOMAIN_COUNT = UPG_DOMAINS.length;
 var UPG_EDGE_COUNT = UPG_EDGE_TYPES.length;
 var UPG_META_COUNT = UPG_ENTITY_META.length;
+var UPG_PHASE_COUNT = (() => {
+  const pairs = /* @__PURE__ */ new Set();
+  for (const lifecycle of UPG_LIFECYCLES) {
+    const owner = lifecycle.template_id ? `T:${lifecycle.template_id}` : `E:${lifecycle.entity_type}`;
+    for (const phase of lifecycle.phases) pairs.add(`${owner}::${phase.id}`);
+  }
+  return pairs.size;
+})();
 export {
   ACTIVE_WHEN_PROPERTY,
   ANALYTICS_DATA_PLAYBOOK,
@@ -33110,10 +33310,12 @@ export {
   CONFIGURATION_VARIANCE_EDGE_PROPERTY_SCHEMA,
   CONTENT_DEPTH_WARNING_RULES,
   COVERAGE_ANTI_PATTERNS,
+  CROSS_EDGE_KEY_ORDER,
   DEFAULT_ENTITY_EMOJI,
   DEFERRED_PROPOSED_BY_CONTRACT,
   DEFER_EDGE_PROPERTY_SCHEMA,
   DISCOVERY_RESEARCH_VALIDATION_PLAYBOOK,
+  EDGE_KEY_ORDER,
   ENGINEERING_PLATFORM_PLAYBOOK,
   ENTITY_EMOJI,
   EXPERIENCE_DESIGN_BRAND_PLAYBOOK,
@@ -33181,7 +33383,9 @@ export {
   UPG_LIFECYCLE_PLANNED_TYPES,
   UPG_META_COUNT,
   UPG_MIGRATIONS,
+  UPG_PHASE_COUNT,
   UPG_PLAYBOOKS,
+  UPG_POLYMORPHIC_EDGE_FAMILIES,
   UPG_POLYMORPHIC_EDGE_KEYS,
   UPG_PORTFOLIO_KINDS,
   UPG_PORTFOLIO_SHARED_TYPES,