@intentset/core 0.5.0 → 0.6.0

package/src/read-export.ts

@@ -26,10 +26,14 @@ import {
   ID_PATTERN,
   LEVELS,
   LINK_KINDS,
+  MEASURE_DIRECTIONS,
+  METRIC_PATTERN,
   OWNERSHIP_REGIONS,
   STATUSES,
   SUPPORTED_EXPORT_CONTRACTS,
   ARTIFACT_TYPES,
+  TIP_MAX_LENGTH,
+  TIP_PATTERN,
   VISIBILITIES,
 } from "./types.ts";
 
@@ -364,9 +368,18 @@ class Shape {
 
   registries(value: unknown): void {
     const at = "/registries";
-    const r = this.object(value, at, ["owners", "audiences", "releases", "roles", "editions", "flags", "resources"]);
+    const r = this.object(value, at, [
+      "owners",
+      "audiences",
+      "releases",
+      "roles",
+      "editions",
+      "flags",
+      "evidenceSources",
+      "resources",
+    ]);
     if (r === null) return;
-    for (const key of ["owners", "audiences", "releases", "roles", "editions", "flags"])
+    for (const key of ["owners", "audiences", "releases", "roles", "editions", "flags", "evidenceSources"])
       this.strings(r[key], `${at}/${key}`);
     this.array(r.resources, `${at}/resources`, (resource, p) => {
       const x = this.object(resource, p, ["id", "path", "owner", "consumers"]);
@@ -401,6 +414,8 @@ class Shape {
         "availability",
         "slice",
         "verification",
+        "measure",
+        "tips",
         "extensions",
       ],
       ["body"],
@@ -444,6 +459,27 @@ class Shape {
       this.string(v.locator, `${p}/locator`);
       this.string(v.selector, `${p}/selector`);
     });
+    this.nullable(a.measure, `${at}/measure`, (x, p) => {
+      const m = this.object(x, p, ["metric", "baseline", "target", "window", "source", "direction"]);
+      if (m === null) return;
+      this.string(m.metric, `${p}/metric`, METRIC_PATTERN, "a metric identifier such as median_time_to_intervention");
+      for (const key of ["baseline", "target", "window", "source"]) this.string(m[key], `${p}/${key}`);
+      this.nullable(m.direction, `${p}/direction`, (d, q) => this.oneOf(d, q, MEASURE_DIRECTIONS));
+    });
+    this.nullable(a.tips, `${at}/tips`, (x, p) => {
+      if (!isRecord(x)) {
+        this.fail(p, "Expected an object of tips by explained ID.");
+        return;
+      }
+      for (const key of Object.keys(x).sort(compareStrings)) {
+        const q = `${p}/${key}`;
+        if (!ID_PATTERN.test(key)) this.fail(q, "Expected an artifact ID as the key.");
+        const tip = x[key];
+        if (typeof tip !== "string" || tip.length > TIP_MAX_LENGTH || !TIP_PATTERN.test(tip)) {
+          this.fail(q, `Expected one line of plain text, at most ${TIP_MAX_LENGTH} characters.`);
+        }
+      }
+    });
     this.nullable(a.extensions, `${at}/extensions`, (x, p) => this.extensions(x, p));
     if (Object.hasOwn(a, "body") && typeof a.body !== "string") this.fail(`${at}/body`, "Expected a string.");
   }

package/src/registries.ts

@@ -1,6 +1,6 @@
 /**
- * The repository registries (Core §4, §7; VSA §3): owners, audiences, the
- * four release dimensions, and the shared-resource inventory. The file is
+ * The repository registries (Core §4, §6, §7; VSA §3): owners, audiences, the
+ * four release dimensions, the evidence sources measures name, and the shared-resource inventory. The file is
  * `registries.yaml` in the shape of examples/scheduling/registries.yaml.
  * A missing or empty file is empty registries, which the validator reads as
  * "not declared" rather than "nothing allowed".
@@ -10,7 +10,7 @@ import { compareStrings, isRecord, makeDiagnostic } from "./report.ts";
 import { EMPTY_REGISTRIES, ID_PATTERN, type Registries, type Resource } from "./types.ts";
 import { parseYamlDetailed } from "./yaml.ts";
 
-const LIST_KEYS = ["owners", "audiences", "releases", "roles", "editions", "flags"] as const;
+const LIST_KEYS = ["owners", "audiences", "releases", "roles", "editions", "flags", "evidenceSources"] as const;
 const KNOWN_KEYS = new Set<string>([...LIST_KEYS, "resources"]);
 
 /**

package/src/types.ts

@@ -10,6 +10,7 @@ export const ARTIFACT_TYPES = [
   "product",
   "intent",
   "outcome",
+  "measure",
   "capability",
   "behavior",
   "rule",
@@ -75,6 +76,7 @@ export const LINK_ENDPOINTS: Record<
 export const PARENT_TARGETS: Partial<Record<ArtifactType, readonly ArtifactType[]>> = {
   intent: ["product"],
   outcome: ["intent"],
+  measure: ["outcome"],
   capability: ["outcome", "capability"],
   behavior: ["capability"],
 };
@@ -84,6 +86,7 @@ export const REQUIRED_SECTIONS: Record<ArtifactType, readonly string[]> = {
   product: ["Scope"],
   intent: ["Rationale"],
   outcome: ["Measure"],
+  measure: ["Method"],
   capability: ["Overview"],
   behavior: ["Behavior", "Preconditions", "Outcomes"],
   rule: ["Constraint"],
@@ -135,6 +138,28 @@ export interface VerificationMeta {
   selector: string;
 }
 
+export const MEASURE_DIRECTIONS = ["increase", "decrease"] as const;
+export type MeasureDirection = (typeof MEASURE_DIRECTIONS)[number];
+
+/** Core §6: a metric identifier, lower case, words joined by `_` or `-`. */
+export const METRIC_PATTERN = /^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$/;
+
+/** The literal a measure's baseline carries when none has been taken yet (Core §6). */
+export const BASELINE_UNKNOWN = "unknown";
+
+/** Core §6 measure metadata: how the parent outcome is judged. */
+export interface MeasureMeta {
+  metric: string;
+  /** A value, or `unknown` (BASELINE_UNKNOWN). */
+  baseline: string;
+  target: string;
+  /** When the measure is read, relative to a release or a date; prose, not parsed. */
+  window: string;
+  /** An entry in the repository's `evidenceSources` registry. */
+  source: string;
+  direction?: MeasureDirection;
+}
+
 /** The `intentset` block of a document's frontmatter after validation, Core §4. */
 export interface ArtifactMeta {
   spec: typeof SPEC_VERSION;
@@ -158,6 +183,7 @@ export interface ArtifactMeta {
   tips?: Record<string, string>;
   slice?: SliceMeta;
   verification?: VerificationMeta;
+  measure?: MeasureMeta;
 }
 
 export interface Heading {
@@ -234,6 +260,8 @@ export interface Registries {
   roles: string[];
   editions: string[];
   flags: string[];
+  /** Where a measure's evidence is expected to come from (Core §6): an analytics product, a study, a survey. */
+  evidenceSources: string[];
   resources: Resource[];
 }
 
@@ -244,6 +272,7 @@ export const EMPTY_REGISTRIES: Registries = {
   roles: [],
   editions: [],
   flags: [],
+  evidenceSources: [],
   resources: [],
 };
 
@@ -303,11 +332,12 @@ export interface ImpactReport {
 }
 
 /**
- * The versioned export envelope (spec/export.md; spec/export.schema.json). 0.2 is
- * the first version a consumer may pin: 0.1 carried untyped report slots and
- * restricted artifacts by default (ADR 0008).
+ * The versioned export envelope (spec/export.md; spec/export.schema.json). 0.2 was
+ * the first version a consumer could pin: 0.1 carried untyped report slots and
+ * restricted artifacts by default (ADR 0008). 0.3 added the measure type, the
+ * `evidenceSources` registry, and `measure` and `tips` on every artifact (ADR 0012).
  */
-export const EXPORT_CONTRACT = "intentset/export/0.2";
+export const EXPORT_CONTRACT = "intentset/export/0.3";
 
 /** The contracts this implementation reads. A consumer rejects every other value (spec/export.md §5). */
 export const SUPPORTED_EXPORT_CONTRACTS: readonly string[] = [EXPORT_CONTRACT];
@@ -338,6 +368,10 @@ export interface ExportArtifact {
   availability: Availability | null;
   slice: SliceMeta | null;
   verification: VerificationMeta | null;
+  /** Null unless the artifact is a measure; `direction` is null when the author set none. */
+  measure: (Omit<MeasureMeta, "direction"> & { direction: MeasureDirection | null }) | null;
+  /** Null unless the artifact is knowledge with tips (Core §9). */
+  tips: Record<string, string> | null;
   extensions: Record<string, unknown> | null;
   /** Present only when the export was asked to include bodies. */
   body?: string;

package/src/validate.ts

@@ -414,6 +414,18 @@ function checkLifecycle(context: Context): void {
         });
       }
     }
+    if (meta.measure !== undefined) {
+      if (registries.evidenceSources.length === 0) use("evidenceSources");
+      else if (!registries.evidenceSources.includes(meta.measure.source)) {
+        reportOn(context, artifact, {
+          code: "CORE005",
+          field: "/intentset/measure/source",
+          message: `measure source ${meta.measure.source} is not in the evidenceSources registry.`,
+          remediation:
+            "Add the analytics product, study or survey to registries.yaml evidenceSources, or name a registered source.",
+        });
+      }
+    }
     meta.slice?.usesResources.forEach((resource, i) => {
       if (registries.resources.length === 0) use("resources");
       else if (!resourceIds.has(resource)) {
@@ -465,12 +477,22 @@ interface Requirement {
   remediation: string;
   /** Core §5 names no active obligation for this type; only the draft warning applies. */
   draftOnly?: boolean;
+  /** Only edges from these types count: an outcome is judged by its measures, not by the capabilities under it. */
+  fromTypes?: readonly ArtifactType[];
 }
 
 function requirement(artifact: Artifact): Requirement | null {
   const { meta } = artifact;
   const id = meta.id;
   switch (meta.type) {
+    case "outcome":
+      return {
+        kinds: ["parent"],
+        direction: "in",
+        fromTypes: ["measure"],
+        message: "no measure names it as parent, so nothing says how it will be judged",
+        remediation: `Add a measure record with \`parent: ${id}\` carrying metric, baseline, target, window and source (Core §6).`,
+      };
     case "rule":
       return {
         kinds: ["governedBy"],
@@ -529,18 +551,27 @@ function requirement(artifact: Artifact): Requirement | null {
 }
 
 /**
- * Core §5 and VSA §3: active rules, scenarios, verifications, knowledge and
- * product slices are attached (CORE003). Their drafts, and draft contracts
- * and decisions nothing refers to, are unattached drafts (CORE009, warning).
+ * Core §5, §6 and VSA §3: active rules, scenarios, verifications, knowledge and
+ * product slices are attached, and an active outcome has a measure (CORE003).
+ * Their drafts, and draft contracts and decisions nothing refers to, are
+ * unattached drafts (CORE009, warning).
  */
 function checkAttachment(context: Context): void {
   const { graph } = context;
   for (const artifact of sortedArtifacts(graph)) {
     const need = requirement(artifact);
     if (need === null || artifact.meta.status === "retired") continue;
-    const edges = need.kinds.flatMap((kind) =>
-      need.direction === "in" ? incomingEdges(graph, artifact.meta.id, kind) : outgoing(graph, artifact.meta.id, kind),
-    );
+    const edges = need.kinds
+      .flatMap((kind) =>
+        need.direction === "in"
+          ? incomingEdges(graph, artifact.meta.id, kind)
+          : outgoing(graph, artifact.meta.id, kind),
+      )
+      .filter((edge) => {
+        if (need.fromTypes === undefined) return true;
+        const from = graph.artifacts.get(edge.from);
+        return from !== undefined && need.fromTypes.includes(from.meta.type);
+      });
     if (edges.length > 0) continue;
     const field = need.direction === "out" ? `/intentset/links/${need.kinds[0]}` : undefined;
     if (artifact.meta.status === "draft") {
@@ -572,7 +603,7 @@ export function patternProblem(pattern: string): string | null {
   return null;
 }
 
-/** VSA §3 and Core §8: type-specific blocks on their own type only; technical slices give a rationale and implement nothing; patterns are plain. */
+/** VSA §3, Core §6 and §8: type-specific blocks on their own type only; technical slices give a rationale and implement nothing; patterns are plain. */
 function checkSlices(context: Context): void {
   const { graph } = context;
   for (const artifact of sortedArtifacts(graph)) {
@@ -586,6 +617,13 @@ function checkSlices(context: Context): void {
         "Remove the verification block, or change the type (Core §8).",
       );
     }
+    if (artifact.meta.measure !== undefined && artifact.meta.type !== "measure") {
+      profile(
+        "/intentset/measure",
+        `${id} is ${aType(artifact.meta.type)} and carries measure metadata, which only a measure has.`,
+        "Remove the measure block, or change the type (Core §6).",
+      );
+    }
     const slice = artifact.meta.slice;
     if (slice === undefined) continue;
     if (artifact.meta.type !== "slice") {