@skill-map/spec 0.19.0 → 0.21.0

package/schemas/{view-contracts.schema.json → view-slots.schema.json}

@@ -1,47 +1,52 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/view-contracts.schema.json",
-  "title": "ViewContracts",
-  "description": "Closed catalog of view contracts. A view contract is a semantic spec a plugin author picks by name to surface per-node (or per-scope) data in the UI without shipping any UI code. The kernel publishes this catalog; plugin authors pick by `contract` name in their extension manifest's `viewContributions` map; the UI driving adapter maps `contract → slot(s) + renderer` (slot policy is UI-only, kernel does not know about slots). The plugin emits per-node payloads via `ctx.emitContribution(id, payload)` — payloads are validated at emit time against the contract's payload schema in `$defs.payloads`. Closed catalog by design: every new contract requires a spec change + UI renderer + scaffolder support + conformance fixtures + tests. Compounds catalog evolution cost; see ROADMAP.md §UI contribution system → 'Known limitations carried forward'. Contracts are versioned via the manifest field `catalogCompat` (semver against the catalog as a whole), not per-contract.",
+  "$id": "https://skill-map.dev/spec/v0/view-slots.schema.json",
+  "title": "ViewSlots",
+  "description": "Closed catalog of view slots. A view slot is a kernel-published handle that names a visual surface in the UI, fixes the renderer that draws there, and fixes the payload shape the plugin emits. The plugin author picks ONE slot per view contribution; the kernel validates `ctx.emitContribution(id, payload)` against that slot's payload schema in `$defs.payloads`. There is no separate notion of a 'contract' — the slot IS the contract. Closed catalog by design: every new slot requires a spec change + UI renderer mount + scaffolder support + conformance fixtures + tests. Compounds catalog evolution cost; see ROADMAP.md §UI contribution system → 'Known limitations carried forward'. Slots are versioned via the manifest field `catalogCompat` (semver against the catalog as a whole), not per-slot.",
   "type": "object",
   "$defs": {
-    "ContractName": {
+    "SlotName": {
       "type": "string",
       "enum": [
-        "node-counter",
-        "node-tag",
-        "node-breakdown",
-        "node-records",
-        "node-tree",
-        "node-key-values",
-        "node-link-list",
-        "node-markdown",
-        "node-alert",
-        "scope-stat"
+        "card.title.right",
+        "card.subtitle.left",
+        "card.footer.left",
+        "card.footer.right",
+        "graph.node.alert",
+        "inspector.header.badge.counter",
+        "inspector.header.badge.tag",
+        "inspector.body.panel.breakdown",
+        "inspector.body.panel.records",
+        "inspector.body.panel.tree",
+        "inspector.body.panel.key-values",
+        "inspector.body.panel.link-list",
+        "inspector.body.panel.markdown",
+        "topbar.nav.start"
       ],
-      "description": "Closed enum of contract identifiers. Adding an entry requires the full spec/UI/scaffolder/conformance round-trip per ROADMAP.md §UI contribution system. Removing or renaming an entry is a catalog-major-bump and triggers `sm plugins upgrade` migration."
+      "description": "Closed enum of slot identifiers. Adding an entry requires the full spec/UI/scaffolder/conformance round-trip per ROADMAP.md §UI contribution system. Removing or renaming an entry is a catalog-major-bump and triggers `sm plugins upgrade` migration. Slots that share a payload shape (e.g. `card.subtitle.left`, `card.footer.right`, and `card.footer.left` all carry a counter) reference the same payload schema in `$defs.payloads`."
     },
     "Severity": {
       "type": "string",
       "enum": ["info", "warn", "success", "danger"],
-      "description": "Closed severity palette aligned with PrimeNG `<p-tag>` / `<p-message>` severities. Used by `node-counter`, `node-tag`, and `node-alert` for color/contrast hints. The UI maps each severity to a theme-aware tint; plugins do not pick raw colors."
+      "description": "Closed severity palette aligned with PrimeNG `<p-tag>` / `<p-message>` severities. Used by counter, tag, alert, and icon slots for color/contrast hints. The UI maps each severity to a theme-aware tint; plugins do not pick raw colors."
     },
     "IconString": {
       "type": "string",
       "minLength": 1,
       "maxLength": 64,
-      "description": "Single string, dual-resolved by the UI. If the value matches a Unicode `\\p{Extended_Pictographic}` codepoint, render as emoji text. Otherwise resolve as a PrimeIcons class id (without the `pi-` prefix; the UI prepends it). Unknown PrimeIcons names render no icon (silent fallback) plus a console warning. The plugin author types either the emoji character or the icon name; the discrimination is automatic."
+      "pattern": "^(?:pi pi-[a-z0-9-]+|pi-[a-z0-9-]+|fa-(?:solid|regular|brands) fa-[a-z0-9-]+|fa-[a-z0-9-]+|[^a-zA-Z].*)$",
+      "description": "Single string, prefix-discriminated by the UI. Four valid shapes: (1) emoji — any value starting with a non-ASCII-letter codepoint renders as text; (2) PrimeIcons — `pi-foo` or `pi pi-foo` renders as `<i class=\"pi pi-foo\">`; (3) FontAwesome explicit family — `fa-solid fa-foo` / `fa-regular fa-foo` / `fa-brands fa-foo` passes through as-is; (4) FontAwesome shorthand — `fa-foo` (no family token) defaults to `fa-solid fa-foo`. Bare class names without a `pi-` / `fa-` prefix are rejected at manifest load (invalid-manifest). Unknown PrimeIcons / FontAwesome names render no icon (silent fallback) plus a console warning."
     },
     "IViewContribution": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["contract"],
+      "required": ["slot"],
       "properties": {
-        "contract": { "$ref": "#/$defs/ContractName" },
+        "slot": { "$ref": "#/$defs/SlotName" },
         "label": {
           "type": "string",
           "maxLength": 64,
-          "description": "Short human-readable label. Used as metadata (docs / plugin-doctor / aria-label) and, for some contracts, rendered in the chip / panel header / table label. English-only per AGENTS.md (`Externalized texts, not internationalized`). Per-contract notes specify whether it is rendered inline; `node-counter` keeps it as metadata only."
+          "description": "Short human-readable label. Used as metadata (docs / plugin-doctor / aria-label) and, for some slots, rendered in the chip / panel header / table label. English-only per AGENTS.md (`Externalized texts, not internationalized`). Per-slot notes specify whether it is rendered inline; counter slots keep it as metadata only."
         },
         "tooltip": {
           "type": "string",
@@ -52,12 +57,12 @@
         "emptyText": {
           "type": "string",
           "maxLength": 128,
-          "description": "Text shown in the empty placeholder when the contract permits an empty payload. Defaults to a UI-supplied generic 'No data.' string. English-only."
+          "description": "Text shown in the empty placeholder when the slot permits an empty payload. Defaults to a UI-supplied generic 'No data.' string. English-only."
         },
         "emitWhenEmpty": {
           "type": "boolean",
           "default": false,
-          "description": "When false (default), the kernel drops emissions whose payload is structurally empty (zero counter value, empty array, empty tree, etc.) so the slot stays silent. When true, the renderer surfaces an empty placeholder instead. Per-contract definition of 'empty' lives in the contract's payload schema notes."
+          "description": "When false (default), the kernel drops emissions whose payload is structurally empty (zero counter value, empty array, empty tree, etc.) so the slot stays silent. When true, the renderer surfaces an empty placeholder instead. Per-slot definition of 'empty' lives in the payload schema notes."
         },
         "priority": {
           "type": "number",
@@ -67,15 +72,47 @@
       },
       "allOf": [
         {
-          "if": { "properties": { "contract": { "const": "node-counter" } } },
-          "then": { "required": ["contract", "icon"] }
+          "if": {
+            "properties": {
+              "slot": {
+                "enum": [
+                  "card.subtitle.left",
+                  "card.footer.left",
+                  "card.footer.right",
+                  "inspector.header.badge.counter"
+                ]
+              }
+            }
+          },
+          "then": { "required": ["slot", "icon"] }
+        },
+        {
+          "if": { "properties": { "slot": { "const": "card.title.right" } } },
+          "then": { "required": ["slot", "icon"] }
         }
       ],
-      "description": "Manifest-side declaration of a single view contribution, keyed in `IExtensionBase.viewContributions[<contributionId>]`. The plugin author picks the contract by name; the rest is presentation tuning. The plugin NEVER picks a slot — the UI maps contract → slot(s). Some contracts add per-contract requireds (e.g. `node-counter` requires `icon`)."
+      "description": "Manifest-side declaration of a single view contribution, keyed in `IExtensionBase.viewContributions[<contributionId>]`. The plugin author picks ONE slot from the closed `SlotName` enum; the slot fixes the renderer and the payload shape. Slots whose renderer is the counter chip require `icon` in the manifest; same for `card.title.right` (the standalone icon slot)."
     },
     "payloads": {
-      "description": "Per-contract payload schemas, keyed by contract name. The kernel validates `ctx.emitContribution(id, payload)` calls against the entry corresponding to the declared contract before persisting to `scan_contributions`. Off-contract payloads emit an `extension.error` event and drop silently (mirror of `emitLink` off-contract drop pattern).",
-      "node-counter": {
+      "description": "Per-slot payload schemas. The kernel validates `ctx.emitContribution(id, payload)` calls against the entry corresponding to the declared slot before persisting to `scan_contributions`. Off-shape payloads emit an `extension.error` event and drop silently (mirror of `emitLink` off-contract drop pattern). Slots that share a renderer share a payload shape; the schema is defined inline at each slot to keep lookups direct (no internal indirection).",
+      "card.title.right": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "icon": {
+            "$ref": "#/$defs/IconString",
+            "description": "Optional payload-time icon override. When omitted the manifest-declared `icon` (which is required for this slot — see `IViewContribution.allOf`) is rendered instead. Lets a plugin emit a different icon per node without redeclaring the manifest."
+          },
+          "severity": { "$ref": "#/$defs/Severity" },
+          "tooltip": { "type": "string", "maxLength": 256 }
+        },
+        "description": "Single icon per node — small standalone marker rendered next to the card title. The manifest requires `icon`; the payload optionally overrides it per node and may add `severity` (color tint) and `tooltip`. No counts, no labels — for chip + number use a counter slot; for label + severity use a tag slot. 'Empty' for `emitWhenEmpty` is the absence of both payload `icon` and a manifest fallback (in practice never empty since the manifest icon is required)."
+      },
+      "card.subtitle.left": { "$ref": "#/$defs/payloads/_counter" },
+      "card.footer.left": { "$ref": "#/$defs/payloads/_counter" },
+      "card.footer.right": { "$ref": "#/$defs/payloads/_counter" },
+      "inspector.header.badge.counter": { "$ref": "#/$defs/payloads/_counter" },
+      "_counter": {
         "type": "object",
         "additionalProperties": false,
         "required": ["value"],
@@ -91,9 +128,10 @@
             "description": "Optional severity for visual tinting. The slot decides whether to honour it (`SLOT_REGISTRY[slot].respectSeverity`). The plugin emits the data; the UI decides the presentation."
           }
         },
-        "description": "Single icon + integer pair, modelled after the `.sm-gnode__stat` rows in the card footer. Manifest requires `icon`; payload carries `value`, optionally `severity` and `tooltip`. The manifest `label` is metadata (docs / plugin-doctor / aria-label) and is NOT rendered inline."
+        "description": "Single icon + integer pair, modelled after the `.sm-gnode__stat` rows in the card footer. Manifest requires `icon` (enforced by `IViewContribution.allOf` for every counter slot); payload carries `value`, optionally `severity` and `tooltip`. The manifest `label` is metadata (docs / plugin-doctor / aria-label) and is NOT rendered inline."
       },
-      "node-tag": {
+      "inspector.header.badge.tag": { "$ref": "#/$defs/payloads/_tag" },
+      "_tag": {
         "type": "object",
         "additionalProperties": false,
         "required": ["label"],
@@ -108,7 +146,23 @@
           "tooltip": { "type": "string", "maxLength": 256 }
         }
       },
-      "node-breakdown": {
+      "graph.node.alert": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "icon": { "$ref": "#/$defs/IconString" },
+          "severity": { "$ref": "#/$defs/Severity" },
+          "count": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 99,
+            "description": "Optional badge count rendered next to the icon (1-99; 99+ collapses to '99+'). Omit for an icon-only marker."
+          },
+          "tooltip": { "type": "string", "maxLength": 256 }
+        },
+        "description": "Decoration on the graph node (corner badge / pin). At least one of `icon`, `severity`, `count` is required. 'Empty' for `emitWhenEmpty` is the absence of `icon` AND `count`. Hard cap 1 marker per node per plugin extension (slot config enforces)."
+      },
+      "inspector.body.panel.breakdown": {
         "type": "object",
         "additionalProperties": false,
         "required": ["entries"],
@@ -130,7 +184,7 @@
           }
         }
       },
-      "node-records": {
+      "inspector.body.panel.records": {
         "type": "object",
         "additionalProperties": false,
         "required": ["columns", "rows"],
@@ -168,7 +222,7 @@
           }
         }
       },
-      "node-tree": {
+      "inspector.body.panel.tree": {
         "$ref": "#/$defs/payloads/_TreeNode",
         "description": "Recursive tree rendered as an indented hierarchy. Hard caps: max depth 6, max 200 total nodes per tree (validator enforces). 'Empty' for `emitWhenEmpty` is the root having no `children`."
       },
@@ -186,7 +240,7 @@
           }
         }
       },
-      "node-key-values": {
+      "inspector.body.panel.key-values": {
         "type": "object",
         "additionalProperties": false,
         "required": ["entries"],
@@ -215,7 +269,7 @@
           }
         }
       },
-      "node-link-list": {
+      "inspector.body.panel.link-list": {
         "type": "object",
         "additionalProperties": false,
         "required": ["entries"],
@@ -232,7 +286,7 @@
                   "type": "string",
                   "minLength": 1,
                   "maxLength": 512,
-                  "description": "Node path within the scope. Resolved by the UI to a clickable link via `Router.navigate` — never rendered as a raw `[href]` (per the renderer attr-sanitization rule)."
+                  "description": "Node path within the scope. Resolved by the UI to a clickable link via `Router.navigate` — never rendered as a raw `[href]` (per the renderer attr-sanitization analyzer)."
                 },
                 "label": { "type": "string", "minLength": 1, "maxLength": 128 },
                 "kind": {
@@ -247,7 +301,7 @@
           }
         }
       },
-      "node-markdown": {
+      "inspector.body.panel.markdown": {
         "type": "object",
         "additionalProperties": false,
         "required": ["markdown"],
@@ -259,23 +313,7 @@
           }
         }
       },
-      "node-alert": {
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-          "icon": { "$ref": "#/$defs/IconString" },
-          "severity": { "$ref": "#/$defs/Severity" },
-          "count": {
-            "type": "integer",
-            "minimum": 1,
-            "maximum": 99,
-            "description": "Optional badge count rendered next to the icon (1-99; 99+ collapses to '99+'). Omit for an icon-only marker."
-          },
-          "tooltip": { "type": "string", "maxLength": 256 }
-        },
-        "description": "Decoration on the graph node (corner badge / pin). At least one of `icon`, `severity`, `count` is required. 'Empty' for `emitWhenEmpty` is the absence of `icon` AND `count`. Hard cap 1 marker per node per plugin extension (slot config enforces)."
-      },
-      "scope-stat": {
+      "topbar.nav.start": {
         "type": "object",
         "additionalProperties": false,
         "required": ["value"],
@@ -285,13 +323,13 @@
               { "type": "integer", "minimum": 0 },
               { "type": "string", "minLength": 1, "maxLength": 64 }
             ],
-            "description": "Either a non-negative integer or a short string. The UI renders it as a single chip in `topbar.actions.indicator`."
+            "description": "Either a non-negative integer or a short string. The UI renders it as a single chip in the topbar."
           },
           "label": { "type": "string", "minLength": 1, "maxLength": 32 },
           "tooltip": { "type": "string", "maxLength": 256 },
           "severity": { "$ref": "#/$defs/Severity" }
         },
-        "description": "Single value summarizing the entire scope. Emitted ONCE per scan (not per node). Plugins use `ctx.emitScopeContribution(...)` (rule context) — extractors do not see `emitScopeContribution`."
+        "description": "Single value summarizing the entire scope. Emitted ONCE per scan (not per node). Plugins use `ctx.emitScopeContribution(...)` (analyzer context) — extractors do not see `emitScopeContribution`."
       }
     }
   }

package/schemas/extensions/rule.schema.json

@@ -1,43 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/extensions/rule.schema.json",
-  "title": "ExtensionRule",
-  "description": "Manifest shape for a `Rule` extension. A rule consumes the full graph (nodes + links) after all extractors have run and emits `Issue[]`. Rules are dual-mode: `deterministic` rules MUST be byte-for-byte reproducible (same graph in → same issues out; time, random, and network are forbidden) and run synchronously inside `sm check` / `sm scan`. `probabilistic` rules invoke an LLM through the kernel's `RunnerPort` and execute only as queued jobs (`sm job submit rule:<id>`); their output MAY vary across runs and they NEVER participate in `sm scan`. See `architecture.md` §Execution modes for the full contract.",
-  "allOf": [
-    { "$ref": "base.schema.json" }
-  ],
-  "type": "object",
-  "required": ["id", "kind", "version", "emitsRuleIds", "defaultSeverity"],
-  "unevaluatedProperties": false,
-  "properties": {
-    "kind": { "const": "rule" },
-    "mode": {
-      "type": "string",
-      "enum": ["deterministic", "probabilistic"],
-      "default": "deterministic",
-      "description": "`deterministic` (default): pure code, byte-for-byte reproducible, runs during `sm check` and `sm scan`. `probabilistic`: invokes an LLM via `ctx.runner` and runs only as a queued job; never participates in scan-time pipelines. The kernel rejects probabilistic rules that try to register scan-time hooks at load time. Omitting the field is equivalent to declaring `deterministic`."
-    },
-    "emitsRuleIds": {
-      "type": "array",
-      "description": "List of `rule_id` values this rule may emit on issues. Typically a singleton (`trigger-collision` → emits `trigger-collision`). A rule emitting a `rule_id` not in this list → kernel logs `rule-id-violation` but keeps the issue (forward compatibility).",
-      "minItems": 1,
-      "items": { "type": "string" }
-    },
-    "defaultSeverity": {
-      "type": "string",
-      "enum": ["error", "warn", "info"],
-      "description": "Severity attached by default to emitted issues. Rules MAY override per-issue."
-    },
-    "consumes": {
-      "type": "string",
-      "enum": ["nodes", "links", "both"],
-      "default": "both",
-      "description": "Which slices of the graph the rule reads. The kernel MAY pass a restricted view when this is a strict subset."
-    },
-    "configurable": {
-      "type": "boolean",
-      "default": false,
-      "description": "If true, the rule reads its own config from `config_preferences` under the key `rules.<id>.<field>`. Implementations MAY surface these in `sm config`."
-    }
-  }
-}