@unified-product-graph/core 0.10.8 → 0.11.1

package/CHANGELOG.md

@@ -7,6 +7,34 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.11.1] - 2026-06-14
+
+**Bug fix: the typed classification writer misrouted competitor sources, duplicated instead of upserting, and disagreed with the confidence scale.** The generic cross-edge writers got their in-place upsert in 0.10.6; the typed convenience writer `create_classification_edge` never inherited it, and on a qualified `{product}/{node}` competitor source it wrote the wrong edge type, created a duplicate, and expanded `high` to a different `confidence_5` value than the rest of the graph. Three defects in one call (Data's dogfood brief), all on a path the generic writers already do correctly. No data migration.
+
+### Fixed
+- **`create_classification_edge` now upserts instead of duplicating.** Root cause was the misroute below: a qualified competitor source was mis-typed as the polymorphic `node_classified_as_classification_value`, so the `(source, target, type)` dedup never matched the existing `competitor_…` edge and a second edge was created. Correct routing makes the write land on the existing cell in place (`status: "updated"`).
+- **Qualified-source type routing.** A `{product}/{node}` source whose node is a `competitor` now resolves to `competitor` — via the owning product file, and failing that the portfolio's `instance_of` index (which maps `{pid}/{nid}` to its canonical type without a local product file) — and writes `competitor_classified_as_classification_value`. Bare local sources keep the polymorphic type.
+- **Confidence-scale agreement.** `high` now expands to `confidence_5` value **4** (canonical label `Confident`), not 5 — matching the generic writers and the existing classify-edge population, so two writers can no longer populate the same axis with different numbers for the same word.
+
+### Added
+- **Pinned friendly confidence mapping on the scale (`confidence_5.friendly_aliases = { low: 2, medium: 3, high: 4 }`).** The single, introspectable source of truth — surfaced via `get_scale` — that `create_classification_edge` (and any future friendly-confidence writer) resolves through `friendlyToAssessment(scaleId, word)`. The expansion carries the canonical point label (`Confident`), not the input word.
+
+---
+
+## [0.11.0] - 2026-06-14
+
+**Self-documenting competitive history: a competitor's classification change records itself.** The 0.10.x tier classifies competitors against axes and values and carries `confidence` / `assessed_on`, but a re-assessment overwrites the prior value — there was no way to ask *what moved*. This release makes the classification landscape remember its own changes. A minor bump: it widens the `competitor_signal.signal_type` enum (union widening), which spec policy treats as a minor; additive, so old graphs still parse.
+
+### Added
+- **`reclassification` shape on `competitor_signal`.** The `signal_type` enum gains `reclassification`, and the type carries four optional transition properties — `competitor` (the classify-edge source, identifying subject + product), `axis`, `from_value`, `to_value`. A reclassification is one more kind of the dated competitor move the entity already models.
+- **Append-only `signals[]` collection on the portfolio document.** A portfolio-scoped, optional, additive collection holding the classification-history stream. Kept here rather than in `registry.nodes` (so it never pollutes the canonical-vocabulary tier or the landscape/tree reads) and rather than in a product graph (so the auto-emit stays atomic with the portfolio cross-edge write). Round-trips through the canonical serializer; portfolios without it stay byte-identical.
+- **`diff_classification` (new tool, 128 total; local-only).** `diff_classification({ product?, competitor?, since? })` reads the reclassification history and projects each move (`from_value` to `to_value` on an axis) with resolved titles, newest first. "Did Sitecore move from integrated to agentic since last quarter" is one call. Pairs with the 0.10.8 freshness filter (which decides *when* to re-assess); this surfaces *what* changed.
+
+### Changed
+- **Classify writes auto-record a move.** When `create_cross_product_edge` / `batch_create_cross_product_edges` create a classify edge that supersedes a sibling classification of the same competitor on the *same axis* (resolved via registry edge or `axis:` tag), the portfolio store appends a `reclassification` signal — completeness by construction, no caller discipline. Record-only and non-destructive: the superseded edge is kept (a `categorical` axis may legitimately carry several values), so current-state reads are untouched. First-time classifications are not moves; unaxed values are skipped (a single-axis move cannot be proven); an identical transition is logged at most once.
+
+---
+
 ## [0.10.8] - 2026-06-14
 
 **Operational tooling for the property layer: coverage audit, write pre-flight, freshness query.** The 218-edge confidence backfill (0.10.6) needed five manual motions the MCP did not expose, mostly `jq` over `portfolio.upg`. This release lands the three near-term ones from Data's tooling-gaps brief. Read-path plus a non-mutating write flag; no schema or data migration.

package/dist/index.cjs

@@ -119,6 +119,7 @@ __export(index_exports, {
   evaluateAntiPatterns: () => evaluateAntiPatterns,
   findInvalidStatusMigrationTargets: () => findInvalidStatusMigrationTargets,
   formatUpgText: () => formatUpgText,
+  friendlyToAssessment: () => friendlyToAssessment,
   generateSlug: () => generateSlug,
   getAnchorEntity: () => getAnchorEntity,
   getAntiPatternById: () => getAntiPatternById,
@@ -6801,7 +6802,11 @@ var UPG_SCALES = {
       { value: 3, label: "Some evidence", description: "A few data points" },
       { value: 4, label: "Confident", description: "Multiple data sources" },
       { value: 5, label: "Data-backed", description: "Strong quantitative evidence" }
-    ]
+    ],
+    // The pinned friendly mapping (0.11.1). `high` is Confident (4), not
+    // Data-backed (5) — 5 is reserved for genuinely quantified claims. Matches
+    // the existing classify-edge population, so nothing needs re-stamping.
+    friendly_aliases: { low: 2, medium: 3, high: 4 }
   },
   // ── Effort ─────────────────────────────────────────────────────────────────
   effort_5: {
@@ -6823,6 +6828,13 @@ var UPG_SCALES = {
 function getScale(scaleId) {
   return UPG_SCALES[scaleId];
 }
+function friendlyToAssessment(scaleId, word) {
+  const scale = UPG_SCALES[scaleId];
+  const value = scale?.friendly_aliases?.[word];
+  if (value === void 0) return null;
+  const point = scale.points.find((p) => p.value === value);
+  return { value, label: point?.label ?? word, scale_id: scaleId };
+}
 var PROPERTY_SCALE_MAP = {
   // ── Reach ────────────────────────────────────────────────────────────────
   reach: "reach_5",
@@ -9949,9 +9961,13 @@ var UPG_PROPERTY_SCHEMA = {
   // CompetitorSignalProperties: Competitor signal: a dated competitor move mapped onto our portfolio.
   competitor_signal: {
     observed_at: { type: "string", description: 'ISO date-time the move was observed. @example "2026-06-10"' },
-    signal_type: { type: "string", enum: ["feature_launch", "pricing_change", "acquisition", "partnership", "market_entry"], description: "Kind of move. `feature_launch` = shipped a feature. `pricing_change` = a plan or tier change. `acquisition` / `partnership` / `market_entry` = strategic moves." },
+    signal_type: { type: "string", enum: ["feature_launch", "pricing_change", "acquisition", "partnership", "market_entry", "reclassification"], description: "Kind of move. `feature_launch` = shipped a feature. `pricing_change` = a plan or tier change. `acquisition` / `partnership` / `market_entry` = strategic moves. `reclassification` = the competitor moved between classification cells on an axis (e.g. ai_integrated to ai_agentic); auto-emitted at the classify-write chokepoint and carries `axis` / `from_value` / `to_value` / `competitor`." },
     summary: { type: "string", description: "One-line factual summary of the move (what shipped, not marketing copy)." },
     impact: { type: "string", enum: ["high", "medium", "low"], description: "Expected impact on our position." },
+    competitor: { type: "string", description: "Reclassification only. The qualified id of the competitor that moved, as the classify cross-edge source (e.g. `p_rival/n_acme`). Identifies both the subject and its owning product, so `diff_classification({ product })` can filter the history stream." },
+    axis: { type: "string", description: "Reclassification only. The `classification_axis` id the move is on (e.g. `ca_ai_maturity`). Mirrors the axis the superseded and new classify edges share." },
+    from_value: { type: "string", description: "Reclassification only. The prior `classification_value` id the competitor was classified as before this move (the superseded cell). Absent for a first-time classification (nothing was superseded)." },
+    to_value: { type: "string", description: "Reclassification only. The new `classification_value` id the competitor is classified as after this move (the cell the new classify edge points at)." },
     last_updated: { type: "string", description: 'Provenance: ISO date-time this record was last observed or refreshed. @example "2026-06-13"' },
     source: { type: "string", description: 'Provenance: where this was observed. A changelog, pricing, or docs URL, an analyst report, or a research note. @example "https://www.contentful.com/changelog/"' },
     confidence: {
@@ -28603,7 +28619,11 @@ function portfolioBody(doc) {
         nodes: sortNodes(doc.registry.nodes).map(canonicalNode),
         ...doc.registry.edges && doc.registry.edges.length > 0 ? { edges: sortEdges(doc.registry.edges).map(canonicalEdge) } : {}
       }
-    } : {}
+    } : {},
+    // Append-only classification-history stream (0.11.0). Emitted only when
+    // non-empty so existing portfolio files without it stay byte-identical.
+    // Each entry is a competitor_signal node (serialised with the node rules).
+    ...doc.signals && doc.signals.length > 0 ? { signals: sortNodes(doc.signals).map(canonicalNode) } : {}
   };
 }
 function computeBodyChecksum(doc) {
@@ -28719,6 +28739,10 @@ function normalizeDocument(obj) {
         ...Array.isArray(rawRegistry.edges) ? { edges: rawRegistry.edges } : {}
       };
     }
+    const rawSignals = raw.signals;
+    if (Array.isArray(rawSignals) && rawSignals.length > 0) {
+      out2.signals = rawSignals.map((n) => repairNodeDrift(n));
+    }
     return out2;
   }
   const out = {
@@ -28743,7 +28767,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.10.8";
+var UPG_VERSION = "0.11.1";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -28907,6 +28931,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   evaluateAntiPatterns,
   findInvalidStatusMigrationTargets,
   formatUpgText,
+  friendlyToAssessment,
   generateSlug,
   getAnchorEntity,
   getAntiPatternById,