Grammar

type Configuration = Readonly<Record<string, string>>

A configuration: axis node id to the single value that holds on it.

type ConfigurationDriftKind = | 'axis_values_empty' | 'axis_default_not_a_value' | 'present_under_empty' | 'present_under_unknown_value' | 'qualifi...

The kinds of configuration drift the validator reports.

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

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

type StatusCategory = | 'triage' | 'backlog' | 'unstarted' | 'started' | 'completed' | 'cancelled'

The near-universal PM-tool status bucket a phase belongs to (0.25.1 feedback 1ee70102) — the same six-bucket system Linear, Jira, Asana, and GitHub Projects converge on.

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 ConfigurationDriftFinding

One configuration-drift finding.

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 ProjectableEdge

The minimum an edge must expose to be projected.

interface ProjectableNode

The minimum a node must expose to be projected.

interface ProjectionResult

Result of a projection: the surviving nodes and edges, plus what it dropped.

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: ProjectableNode[], edges: ProjectableEdge[]) => ConfigurationDriftFinding[]

Check every configuration declaration in a graph.

(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.

(nodes: ProjectableNode[]) => { axis?: string | undefined; value?: string | undefined; configuration: Readonly<Record<string, string>>; }[]

Every configuration this graph can be projected onto, one axis at a time.

() => { 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.

(nodes: N[], edges: E[], configuration: Configuration) => ProjectionResult<N, E>

Project a graph onto one configuration.

(edge: ProjectableEdge) => { axis: string; values: string[]; } | undefined

Read an `active_when` qualifier, or undefined when the edge carries none or carries something malformed.

(properties: Record<string, unknown> | undefined, key: string) => string[] | undefined

Read a string array property defensively; anything else reads as absent.

(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.