Grammar

type CrossProductScope = 'curated' | 'provisional' | 'resident'

The three cross-product states a directed relationship can occupy.

type UPGEdgeMigration = | { kind: 'rename' /** The old edge type key. */ from: string /** The new canonical edge type key. */ to: string /** ...

A single edge-key migration rule.

type UPGPropertyMigration = | { kind: 'drop_props' /** The entity type whose properties are being migrated. */ type: string /** Property keys to ...

A property-level migration applied at load time.

type UPGPropertyMigrationChange = | { kind: 'dropped'; key: string } | { kind: 'renamed_top_level'; from: string; to: string; value_changed: boolean } ...

A single property-migration change applied during `migrateNodeProperties`.

type WalkMigrationChainResult = | { kind: 'canonical'; to: string } | { kind: 'drop' } | { kind: 'dead_end'; last: string } | { kind: 'cycle'; visite...

Walk the edge-migration chain for `edge_type` until reaching a value that exists in `UPG_EDGE_CATALOG` (the current canonical name) or the chain dead-ends.

interface LifecyclePhase

A phase is one broad stage in the entity's lifecycle.

interface LifecycleRenderShape

A flattened, render-ready shape derived from a single `UPGLifecycle`.

interface LifecycleRenderState

A render-ready lifecycle state (one phase of the underlying lifecycle).

interface LifecycleRenderTransition

A render-ready transition between two lifecycle states.

interface LifecycleState

A state is a specific position within a phase.

interface UPGAssessment

An assessment is a human judgment mapped to a numeric scale.

interface UPGEdgeMigrationEndpoints

Endpoint context for `migrateEdge` guard evaluation.

interface UPGEnumScaleDefinition

Runtime metadata for a closed-enum primitive type.

interface UPGEnumScaleValue

A single value in a closed-enum scale

interface UPGLifecycle

A lifecycle defines the valid phase-and-state journey for an entity type.

interface UPGScalarToEdgeMigration

Promote a scalar property that names a first-class entity into a canonical edge.

interface UPGScaleDefinition

A scale definition provides the vocabulary for assessments

interface UPGScalePoint

A single point on an assessment scale

interface UPGSplitEdge

A canonical edge to emit between spawned targets, gated by a condition.

interface UPGSplitMigration

A status-routed 1→N split migration rule.

interface UPGSplitRoute

A single routing rule keyed by source status value.

interface UPGSplitRouteTarget

Per-target route plan: what to spawn and what overrides apply.

interface UPGSplitTarget

A single produced target within a 1→N split.

(node: T, existing: Set<string>) => T

Backfill `slug` on a node if it's missing.

(childType: string, parentType: string) => boolean

Returns `true` if `childType` is a permitted direct child of `parentType` according to the UPG hierarchy.

(nodes: readonly Pick<UPGBaseNode, 'type' | 'slug' | 'aliases'>[], type: string) => Set<string>

Build the existing-slug set for a `(type)` cohort within a single product.

(a: string, b: string) => number

Compare two semver-style version strings of the form `MAJOR.MINOR.PATCH`.

(edgeType: string) => CrossProductScope

Classify an edge TYPE into the 3-state cross-product model.

() => { entity_type: string; from: string; to: string; reason: "no_lifecycle" | "unknown_phase"; }[]

Spec-coherence helper: returns the entity types in `UPG_STATUS_MIGRATIONS` whose registered canonical replacements are NOT valid phases in the type's lifecycle.

(scaleId: string, word: string) => { value: number; label: string; scale_id: string; } | null

Resolve a friendly word (e.g.

(title: string) => string

Generate a slug from a title.

() => Set<string>

Get all deprecated type names (across all versions) as a flat set.

(name: string) => UPGEnumScaleDefinition | undefined

Look up a full enum scale definition by its type name.

(scaleName: string, value: string) => UPGEnumScaleValue | undefined

Look up per-value metadata within a named enum scale.

(entityType: string) => UPGLifecycle | undefined

Returns the lifecycle definition for a given entity type, or `undefined` if the type does not have a lifecycle.

(entityType: string) => LifecycleRenderShape | null

Returns a render-ready `{ states, transitions }` shape for an entity type's lifecycle, or `null` if the type is intentionally lifecycle-free (see {@link UPG_LIFECYCLE_FREE_TYPES}).

(fromVersion: string, toVersion: string) => Record<string, string>

Build a flat old→new type name map for a specific version upgrade.

(scaleId: string) => string[]

Inverse of `PROPERTY_SCALE_MAP`: the canonical property names that default to a given scale, in declaration order.

(_entityType: string, propertyName: string) => string

Return the default scale ID for a given entity-type / property-name pair.

(fromVersion: string, toVersion: string) => UPGPropertyMigration[]

Returns every property migration entry between two versions; useful for load-time warning generation and audit reports.

(fromVersion: string, toVersion: string) => UPGScalarToEdgeMigration[]

Get all scalar→edge promotions between two versions.

(scaleId: string) => UPGScaleDefinition | undefined

Look up a scale definition by its ID.

(fromVersion: string, toVersion: string) => UPGSplitMigration[]

Get all 1→N split migrations between two versions.

(fromVersion: string, toVersion: string) => UPGEdgeMigration[]

Get all edge migration rules between two versions, in version order.

(entityType: string) => readonly string[]

Returns the list of valid child entity types for the given parent type.

(entityType: string, currentStatus: string) => boolean

Return true when the (entityType, currentStatus) pair has a registered canonical replacement that ALSO differs from the current value.

(entityType: string) => boolean

Returns `true` if `entityType` is containment-free, i.e.

(sourceType: string, targetType: string) => boolean

The shared-tier GATE: is a directed edge between these endpoint types authorable across product graphs at all?

(edgeType: string) => boolean

True if this cross-edge type is in the curated canonical set (`UPG_CROSS_EDGE_TYPES`, the 61).

(entityType: string) => boolean

Returns `true` if an entity type is intentionally lifecycle-free (see {@link UPG_LIFECYCLE_FREE_TYPES} for the full list and rationale).

(entityType: string) => boolean

Returns `true` if an entity type has a lifecycle planned for a later phase (see {@link UPG_LIFECYCLE_PLANNED_TYPES}).

(doc: unknown) => boolean

Type guard: returns true if the document is a valid UPGDocument.

() => { entity_type: string; from: string; to: string; }[]

Audit helper: enumerate every (entityType, legacyStatus, canonicalStatus) triple in the registry.

(edge: T, fromVersion: string, toVersion: string, endpoints?: UPGEdgeMigrationEndpoints) => T | null

Apply edge migrations to a single edge.

(node: T, fromVersion: string, toVersion: string) => T

Apply migrations to a single node, converting its type and merging default properties.

(node: T, fromVersion: string, toVersion: string) => { node: T; changes: UPGPropertyMigrationChange[]; }

Apply property migrations to a single node.

(entityType: string, currentStatus: string) => string | null

Look up the canonical replacement for a legacy status value on the given entity type.

(base: string, existing: ReadonlySet<string>) => string

Resolve a base slug against an existing-slug set, appending `-2`, `-3`, etc.

(node: T, next: string) => T

Rotate a slug rename: push the old slug into `aliases[]` (deduped) and set the new slug.

(doc: unknown) => UPGValidationResult

Validates a UPGDocument against the UPG v0.2 specification.