@unified-product-graph/core 0.32.0 → 0.32.1

package/dist/index.d.cts

@@ -12601,7 +12601,10 @@ interface EmptyCell {
 }
 /** ClassificationAxis: a dimension along which subjects are classified.
  *
- * Top-level taxonomy axis hosted by a `competitive_analysis`. Common shapes:
+ * A top-level taxonomy axis, hosted by either a `competitive_analysis` (via
+ * `competitive_analysis_dimensioned_by_classification_axis`) or a `product` (via
+ * `product_dimensioned_by_classification_axis`, added at 0.32.0 so a product can
+ * carry its own label taxonomy without inventing a `tag` entity). Common shapes:
  * "CMS Architecture", "Editing Paradigm", "Database × Workload Type",
  * "IDE × Language Ecosystem".
  *
@@ -14519,6 +14522,36 @@ interface ChangelogProperties {
  * cooldown). Concretely dated (`starts_on` / `ends_on`), which is the deliberate
  * contrast with the freeform `strategic_theme.time_horizon` label a theme carries.
  *
+ * @remarks
+ * THE ACTIVE CYCLE IS THE ONE WHOSE STATUS IS `active`. There is no `is_active`
+ * property and there will not be one: the lifecycle already holds that fact, and
+ * a boolean beside it would be a second source of truth for one thing, which is
+ * a pair that drifts rather than a pair that agrees.
+ *
+ * INVARIANT, documented and deliberately UNENFORCED: at most one `active` cycle
+ * per parent per `cadence_kind`. No check ships for it. The near-miss is real
+ * rather than hypothetical, which is the reason: a portfolio legitimately runs
+ * two products' iterations concurrently, so the rule holds per parent and a
+ * checker would need a graded corpus to tell a violation from that arrangement.
+ * Under the labeled-fixture doctrine a check without such a corpus is one nobody
+ * can defend, so the rule lives here, where an implementer meets it, instead of
+ * in a validator that would be wrong about real graphs.
+ *
+ * ROLLING A CYCLE FORWARD: set cycle N to `closed`, and RE-POINT the unfinished
+ * work's `planning_cycle_schedules_work_item` edges at N+1. A rolled item ends
+ * with ONE edge, not two. The edge means IS SCHEDULED IN, present tense, so a
+ * second edge would assert the item is in both cycles at once.
+ *
+ * The rejected alternative was keeping both edges plus a `rolled_from` edge
+ * property. It builds the deferred scheduling-provenance layer through a side
+ * door, and the corpus shows what it would actually record: six issues
+ * auto-rolled across five cycles with zero completions, which is five edges per
+ * issue documenting that nothing happened.
+ *
+ * Whether the HISTORY of past scheduling is retained is deliberately still open,
+ * deferred alongside the same question for canvas keys rather than answered
+ * twice in two places with two different answers.
+ *
  * @example
  * const properties: PlanningCycleProperties = {
  *   cadence_kind: 'iteration',
@@ -20408,8 +20441,8 @@ interface WorkspaceProperties {
     /**
      * Opaque canvas furniture: the parts of a canvas with no graph referent.
      * Preserved verbatim on round-trip and never interpreted. Tool extension keys
-     * are namespaced `<tool>:<key>` with a colon, and no consumer interprets a key
-     * it does not own.
+     * are namespaced `<tool>:<key>` with a colon (the rule since 0.31.0), and no
+     * consumer interprets a key it does not own.
      *
      * @remarks
      * The cut here is UPG principle P14 applied literally. Anything that is a
@@ -20534,7 +20567,9 @@ interface WorkspaceCanvas {
      * type that forces every conforming consumer to work around it is describing
      * the wrong thing, so the type now says what the doc always did.
      *
-     * THE RULE FOR THESE KEYS (0.31.0):
+     * THE RULE FOR THESE KEYS (0.31.0; the one-release read tolerance for the old
+     * underscore form was retired at 0.32.0, which is a different fact about a
+     * different release and is why the two dates are both correct):
      *  - Syntax is `<tool>:<key>`, with a COLON. An underscore key is indistinguishable
      *    from an ordinary property name, so it cannot be reliably matched, which is
      *    exactly what makes a future migration miss half of what it targets.
@@ -20921,6 +20956,29 @@ interface FrameworkExerciseProperties {
  * to. The genus type; whether it is also a ratified `standard` is carried by
  * `governance`, not the type.
  *
+ * @remarks
+ * CONFORMANCE HAS NO TYPED EDGE TODAY, and this paragraph exists because the
+ * sentence above reads as though it does. "Products implement, expose, or
+ * conform to" names three relationships, and the catalog carries none of them:
+ * everything pointing at `specification` comes from `primitive`,
+ * `operating_lifecycle`, another `specification`, or `organization`. Nothing
+ * comes from `product` or `feature`.
+ *
+ * The cost was measured rather than predicted. A published entity doc, written
+ * by someone reading this very summary, cited
+ * `product_implements_specification`, `product_exposes_specification` and
+ * `feature_conforms_to_specification`. All three are plausible, all three follow
+ * this sentence's own verbs, and none of them has ever existed. The reader did
+ * nothing wrong; the type promised a relationship and the catalog did not
+ * deliver one.
+ *
+ * So, stated plainly until the gap is closed: the central question this type
+ * invites, WHICH PRODUCTS CONFORM TO THIS SPECIFICATION, is not expressible in
+ * typed form. A claim can ride the universal `node_constrains_node`, which is
+ * honest but unqueryable as conformance. Minting a real edge is a MINOR, filed
+ * for 0.33.0 rather than smuggled into a patch, and when it lands this remark
+ * comes out.
+ *
  * @example
  * const properties: SpecificationProperties = {
  *   kind: 'language',
@@ -25480,7 +25538,7 @@ declare function checkHeaderSealText(text: string): UPGHeaderSealReport;
  * it stamps the `upg_version` field of every `.upg` file written by the SDK.
  * The `check:version-lockstep` gate enforces this at release time.
  */
-declare const UPG_VERSION: "0.32.0";
+declare const UPG_VERSION: "0.32.1";
 /**
  * The `.upg` JSON document format version. Written to the `upg_version` field.
  * Evolves independently from `UPG_VERSION` (the catalogue version).

package/dist/index.d.ts

@@ -12601,7 +12601,10 @@ interface EmptyCell {
 }
 /** ClassificationAxis: a dimension along which subjects are classified.
  *
- * Top-level taxonomy axis hosted by a `competitive_analysis`. Common shapes:
+ * A top-level taxonomy axis, hosted by either a `competitive_analysis` (via
+ * `competitive_analysis_dimensioned_by_classification_axis`) or a `product` (via
+ * `product_dimensioned_by_classification_axis`, added at 0.32.0 so a product can
+ * carry its own label taxonomy without inventing a `tag` entity). Common shapes:
  * "CMS Architecture", "Editing Paradigm", "Database × Workload Type",
  * "IDE × Language Ecosystem".
  *
@@ -14519,6 +14522,36 @@ interface ChangelogProperties {
  * cooldown). Concretely dated (`starts_on` / `ends_on`), which is the deliberate
  * contrast with the freeform `strategic_theme.time_horizon` label a theme carries.
  *
+ * @remarks
+ * THE ACTIVE CYCLE IS THE ONE WHOSE STATUS IS `active`. There is no `is_active`
+ * property and there will not be one: the lifecycle already holds that fact, and
+ * a boolean beside it would be a second source of truth for one thing, which is
+ * a pair that drifts rather than a pair that agrees.
+ *
+ * INVARIANT, documented and deliberately UNENFORCED: at most one `active` cycle
+ * per parent per `cadence_kind`. No check ships for it. The near-miss is real
+ * rather than hypothetical, which is the reason: a portfolio legitimately runs
+ * two products' iterations concurrently, so the rule holds per parent and a
+ * checker would need a graded corpus to tell a violation from that arrangement.
+ * Under the labeled-fixture doctrine a check without such a corpus is one nobody
+ * can defend, so the rule lives here, where an implementer meets it, instead of
+ * in a validator that would be wrong about real graphs.
+ *
+ * ROLLING A CYCLE FORWARD: set cycle N to `closed`, and RE-POINT the unfinished
+ * work's `planning_cycle_schedules_work_item` edges at N+1. A rolled item ends
+ * with ONE edge, not two. The edge means IS SCHEDULED IN, present tense, so a
+ * second edge would assert the item is in both cycles at once.
+ *
+ * The rejected alternative was keeping both edges plus a `rolled_from` edge
+ * property. It builds the deferred scheduling-provenance layer through a side
+ * door, and the corpus shows what it would actually record: six issues
+ * auto-rolled across five cycles with zero completions, which is five edges per
+ * issue documenting that nothing happened.
+ *
+ * Whether the HISTORY of past scheduling is retained is deliberately still open,
+ * deferred alongside the same question for canvas keys rather than answered
+ * twice in two places with two different answers.
+ *
  * @example
  * const properties: PlanningCycleProperties = {
  *   cadence_kind: 'iteration',
@@ -20408,8 +20441,8 @@ interface WorkspaceProperties {
     /**
      * Opaque canvas furniture: the parts of a canvas with no graph referent.
      * Preserved verbatim on round-trip and never interpreted. Tool extension keys
-     * are namespaced `<tool>:<key>` with a colon, and no consumer interprets a key
-     * it does not own.
+     * are namespaced `<tool>:<key>` with a colon (the rule since 0.31.0), and no
+     * consumer interprets a key it does not own.
      *
      * @remarks
      * The cut here is UPG principle P14 applied literally. Anything that is a
@@ -20534,7 +20567,9 @@ interface WorkspaceCanvas {
      * type that forces every conforming consumer to work around it is describing
      * the wrong thing, so the type now says what the doc always did.
      *
-     * THE RULE FOR THESE KEYS (0.31.0):
+     * THE RULE FOR THESE KEYS (0.31.0; the one-release read tolerance for the old
+     * underscore form was retired at 0.32.0, which is a different fact about a
+     * different release and is why the two dates are both correct):
      *  - Syntax is `<tool>:<key>`, with a COLON. An underscore key is indistinguishable
      *    from an ordinary property name, so it cannot be reliably matched, which is
      *    exactly what makes a future migration miss half of what it targets.
@@ -20921,6 +20956,29 @@ interface FrameworkExerciseProperties {
  * to. The genus type; whether it is also a ratified `standard` is carried by
  * `governance`, not the type.
  *
+ * @remarks
+ * CONFORMANCE HAS NO TYPED EDGE TODAY, and this paragraph exists because the
+ * sentence above reads as though it does. "Products implement, expose, or
+ * conform to" names three relationships, and the catalog carries none of them:
+ * everything pointing at `specification` comes from `primitive`,
+ * `operating_lifecycle`, another `specification`, or `organization`. Nothing
+ * comes from `product` or `feature`.
+ *
+ * The cost was measured rather than predicted. A published entity doc, written
+ * by someone reading this very summary, cited
+ * `product_implements_specification`, `product_exposes_specification` and
+ * `feature_conforms_to_specification`. All three are plausible, all three follow
+ * this sentence's own verbs, and none of them has ever existed. The reader did
+ * nothing wrong; the type promised a relationship and the catalog did not
+ * deliver one.
+ *
+ * So, stated plainly until the gap is closed: the central question this type
+ * invites, WHICH PRODUCTS CONFORM TO THIS SPECIFICATION, is not expressible in
+ * typed form. A claim can ride the universal `node_constrains_node`, which is
+ * honest but unqueryable as conformance. Minting a real edge is a MINOR, filed
+ * for 0.33.0 rather than smuggled into a patch, and when it lands this remark
+ * comes out.
+ *
  * @example
  * const properties: SpecificationProperties = {
  *   kind: 'language',
@@ -25480,7 +25538,7 @@ declare function checkHeaderSealText(text: string): UPGHeaderSealReport;
  * it stamps the `upg_version` field of every `.upg` file written by the SDK.
  * The `check:version-lockstep` gate enforces this at release time.
  */
-declare const UPG_VERSION: "0.32.0";
+declare const UPG_VERSION: "0.32.1";
 /**
  * The `.upg` JSON document format version. Written to the `upg_version` field.
  * Evolves independently from `UPG_VERSION` (the catalogue version).

package/dist/index.js

@@ -8281,7 +8281,7 @@ var UPG_PROPERTY_MIGRATIONS = {
       kind: "drop_props",
       type: "bug",
       drop_props: ["labels"],
-      reason: "0.32.0: BugProperties.labels duplicated base-node `tags` and had no consumers. Same resolution as task."
+      reason: "0.32.0: BugProperties.labels duplicated base-node `tags` and had no consumers. Freeform labels live in `tags`; grouped labels are classification_axis + node_classified_as_classification_value."
     }
   ],
   // ── v0.21.0: UPG-690 D.1 — collapse residual *_status shadows into status ────
@@ -14362,7 +14362,7 @@ var UPG_PROPERTY_SCHEMA = {
     archived_at: { type: "string", description: "ISO timestamp archived. Pairs with `archived === true`. @deprecated since 0.32.0. Use `UPGBaseNode.archived_at`. Lifted by `UPG_PROPERTY_MIGRATIONS['0.32.0']`." },
     icon: { type: "string", description: "Display icon (emoji or icon name)" },
     retention: { type: "string", enum: ["transient", "durable"], description: "Retention intent. Absent means `transient`.", notes: "A workspace is a free-form thinking space and is transient by default, so the spec makes both intents EXPRESSIBLE and takes no position on which reaches the file. Whether to write a transient canvas at all is a tool decision, and the recommended posture is not to: a scratch canvas nobody named has no business in a shared, git-tracked graph, where it lands in everyone's diff. Writing only `durable` workspaces is what keeps a canonical graph entity comfortable with a transient-by-default object." },
-    canvas: { type: "object", description: "Opaque canvas furniture: the parts of a canvas with no graph referent. Preserved verbatim on round-trip and never interpreted. Tool extension keys are namespaced `<tool>:<key>` with a colon, and no consumer interprets a key it does not own.", notes: "The cut here is UPG principle P14 applied literally. Anything that is a REFERENCE TO A GRAPH NODE is an edge, which is why placed entities ride `workspace_arranges_node` and not this bag: a node id held as a scalar inside a blob is a foreign key in disguise, and a deleted node would leave a stale reference nothing can detect. Anything that is pure UI chrome with no graph referent stays here, because minting `annotation` and `frame` entity types would add catalog surface that is meaningless to every consumer outside the tool that drew it. WHY THE COLON, and why the rule is in the summary rather than buried here. An underscore key is indistinguishable from an ordinary property name, so a migration that targets namespaced keys cannot match it and no validator can detect one that should have been namespaced. That undetectability is why enforcement lives in the type and the documentation instead of in a check: a check would report clean on a bag full of underscore keys, which is worse than no check. Two conventions were already coexisting when this was ruled (`entopo_views` in a live writer, `entopo:view_blocks` in the contract test certifying preservation), which is how a cheap rule becomes a migration. PRESERVATION IS NOT PERMISSION TO RENDER. Preserving every byte says nothing about meaning: a field-measured canvas carried `excluded: true` tombstones, and a consumer that preserved them faithfully while rendering every entry showed the user images they had deleted." }
+    canvas: { type: "object", description: "Opaque canvas furniture: the parts of a canvas with no graph referent. Preserved verbatim on round-trip and never interpreted. Tool extension keys are namespaced `<tool>:<key>` with a colon (the rule since 0.31.0), and no consumer interprets a key it does not own.", notes: "The cut here is UPG principle P14 applied literally. Anything that is a REFERENCE TO A GRAPH NODE is an edge, which is why placed entities ride `workspace_arranges_node` and not this bag: a node id held as a scalar inside a blob is a foreign key in disguise, and a deleted node would leave a stale reference nothing can detect. Anything that is pure UI chrome with no graph referent stays here, because minting `annotation` and `frame` entity types would add catalog surface that is meaningless to every consumer outside the tool that drew it. WHY THE COLON, and why the rule is in the summary rather than buried here. An underscore key is indistinguishable from an ordinary property name, so a migration that targets namespaced keys cannot match it and no validator can detect one that should have been namespaced. That undetectability is why enforcement lives in the type and the documentation instead of in a check: a check would report clean on a bag full of underscore keys, which is worse than no check. Two conventions were already coexisting when this was ruled (`entopo_views` in a live writer, `entopo:view_blocks` in the contract test certifying preservation), which is how a cheap rule becomes a migration. PRESERVATION IS NOT PERMISSION TO RENDER. Preserving every byte says nothing about meaning: a field-measured canvas carried `excluded: true` tombstones, and a consumer that preserved them faithfully while rendering every entry showed the user images they had deleted." }
   }
 };
 function getPropertySchema(entityType) {
@@ -32840,7 +32840,7 @@ function checkHeaderSealText(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.32.0";
+var UPG_VERSION = "0.32.1";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();