@intentset/core 0.6.1 → 0.7.0

package/src/types.ts

@@ -1,10 +1,13 @@
 /**
- * The vocabulary of Core v0.1 (spec/core-0.1.md §2, §4, §5, §7) and the shapes
+ * The vocabulary of Core v0.2 (spec/core-0.2.md §2, §4, §5, §7) and the shapes
  * the packages exchange. This file is the contract; it carries no logic.
  */
 import type { Diagnostic } from "./diagnostics.ts";
 
-export const SPEC_VERSION = "0.1";
+export const SPEC_VERSION = "0.2";
+
+/** The version `SPEC_VERSION` followed (Core §1), named so the error for a record still at it can point to `intentset migrate`. */
+export const PREVIOUS_SPEC_VERSION = "0.1";
 
 export const ARTIFACT_TYPES = [
   "product",
@@ -136,6 +139,8 @@ export interface VerificationMeta {
   method: "automated" | "manual";
   locator: string;
   selector: string;
+  /** Slice or resource IDs the check drives beyond what its behaviors' slices reach (Core §8, ADR 0013); unique. */
+  exercises?: string[];
 }
 
 export const MEASURE_DIRECTIONS = ["increase", "decrease"] as const;
@@ -286,6 +291,20 @@ export interface Config {
   registries: string | null;
   /** Globs excluded from scope and from source enumeration. */
   ignore: string[];
+  /** How run evidence is judged current (Core §8, ADR 0013). */
+  evidence: EvidenceConfig;
+}
+
+/** The two bindings of run evidence to what it checks (Core §8). */
+export const EVIDENCE_BINDINGS = ["subject", "commit"] as const;
+export type EvidenceBinding = (typeof EVIDENCE_BINDINGS)[number];
+
+/** `evidence:` in `.intentset/config.yaml`; both members optional. */
+export interface EvidenceConfig {
+  /** The binding a repository asks for; null leaves the default (subject where slices exist, else commit). */
+  binding: EvidenceBinding | null;
+  /** Files whose change affects every check and that belong to no slice: paths or patterns, mixed into every subject. */
+  globalInputs: string[];
 }
 
 /** Conformance levels, Core §11. Checks above the requested level do not run. */
@@ -336,8 +355,11 @@ export interface ImpactReport {
  * 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).
+ * 0.4 carries the evidence binding: which binding judged each verification, the
+ * subject it was judged at, each record's binding and subject hash, and a
+ * verification's `exercises` (ADR 0014).
  */
-export const EXPORT_CONTRACT = "intentset/export/0.3";
+export const EXPORT_CONTRACT = "intentset/export/0.4";
 
 /** The contracts this implementation reads. A consumer rejects every other value (spec/export.md §5). */
 export const SUPPORTED_EXPORT_CONTRACTS: readonly string[] = [EXPORT_CONTRACT];
@@ -367,7 +389,8 @@ export interface ExportArtifact {
   withheldLinks: number;
   availability: Availability | null;
   slice: SliceMeta | null;
-  verification: VerificationMeta | null;
+  /** `exercises` is the list as authored, less withheld IDs (counted in `withheldLinks`); empty when the record names none. */
+  verification: (Omit<VerificationMeta, "exercises"> & { exercises: string[] }) | 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). */
@@ -377,7 +400,7 @@ export interface ExportArtifact {
   body?: string;
 }
 
-/** A run record as the evidence report carries it: spec/evidence.schema.json's record, unchanged. */
+/** A run record as the evidence report carries it: spec/evidence.schema.json's record, unchanged, `binding` and `subjectHash` included. */
 export interface ExportRunRecord {
   evidenceId: string;
   verificationId: string;
@@ -391,10 +414,18 @@ export interface ExportRunRecord {
   finishedAt: string;
   result: "pass" | "fail" | "skip" | "error";
   uri: string;
+  /** What the record is bound to (Core §8); absent means commit. */
+  binding?: EvidenceBinding;
+  /** The hash of the subject the run checked; present when `binding` is subject. */
+  subjectHash?: string;
   rationale?: string;
   extensions?: Record<string, unknown>;
 }
 
+/** Why the binding of a report is the one in force: the repository asked, the default (subject, since slices claim files), or the fallback to commit for want of slice claims (EVID004). */
+export const EVIDENCE_BINDING_REASONS = ["configured", "default", "no-slices"] as const;
+export type EvidenceBindingReason = (typeof EVIDENCE_BINDING_REASONS)[number];
+
 /** Core §8 freshness, as the evidence check classifies it. Only current-pass is a pass. */
 export const EXPORT_EVIDENCE_STATUSES = [
   "current-pass",
@@ -416,6 +447,10 @@ export interface EvidenceReportSection {
   scope: { product: string; release: string } | null;
   /** Run records read, before classification. */
   records: number;
+  /** The binding the repository judged by (Core §8): every verification below was judged by it. */
+  binding: EvidenceBinding;
+  /** Why: `no-slices` is the fallback to commit binding (EVID004), the only way a repository that asked for nothing is judged by commit. */
+  bindingReason: EvidenceBindingReason;
   /** One per verification artifact, sorted by ID. */
   verifications: ExportVerificationEvidence[];
   /** One per behavior, rule and scenario that is not retired, sorted by ID. */
@@ -426,7 +461,11 @@ export interface ExportVerificationEvidence {
   id: string;
   method: "automated" | "manual";
   status: ExportEvidenceStatus;
-  /** Why the status is qualified, or what was set aside; null when nothing was. */
+  /** The binding that judged it. */
+  binding: EvidenceBinding;
+  /** Under subject binding, the SHA-256 of the verification's subject at this snapshot, which a `subject` record's `subjectHash` must equal to be current; null under commit binding, and when none could be computed. */
+  subject: string | null;
+  /** Why the status is qualified, or what was set aside, and for a stale subject record which part of the subject moved; null when nothing was. */
   note: string | null;
   /** The record that decided the status: the latest at the snapshot, else the latest in scope; null when none. */
   latest: ExportRunRecord | null;

package/src/validate.ts

@@ -438,6 +438,17 @@ function checkLifecycle(context: Context): void {
         });
       }
     });
+    meta.verification?.exercises?.forEach((target, i) => {
+      if (graph.artifacts.get(target)?.meta.type !== "slice" && !resourceIds.has(target)) {
+        reportOn(context, artifact, {
+          code: "CORE003",
+          field: `/intentset/verification/exercises/${i}`,
+          message: `exercises names ${target}, which is neither a slice in the graph nor a resource in the registries.`,
+          remediation:
+            "Name the slice or registry resource the check drives, so a change to its files makes the evidence stale (Core §8), or remove the entry.",
+        });
+      }
+    });
     if (meta.status === "retired" && (meta.links.replacedBy ?? []).length === 0) {
       reportOn(context, artifact, {
         code: "CORE005",