@company-semantics/contracts 84.0.0 → 85.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "84.0.0",
+  "version": "85.0.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/decisions/README.md

@@ -70,6 +70,29 @@ decision-effect-is-a-domain-parameter.
   is a bounded open string because each domain has its own kinds. Promoted
   because the backend renders it and the app consumes it.
 
+## Measured evidence is optional
+
+`confidence` and `signals` on a `DecisionQuestion` are **present only when a
+derivation measured something**. Structure inference measures a model
+confidence and competing signals, so it supplies both. A deterministic
+derivation — Source Sync's synthesis and treatment questions, where a rule fired
+— measured nothing, so it omits both rather than claiming `confidence: 1` and
+`signals: {}`. An unmeasured confidence is not evidence, and one domain never
+invents data to conform to another's historical type (control ADR
+`source-discovery-relevance-funnel`).
+
+- **Readers branch on presence.** Absence means "nothing was measured", which is
+  information; a reader that substitutes a number or an empty record erases it.
+  Nothing in this package defaults either field — no `?? 1`, no `?? {}` — and a
+  test scans `src/decisions/` to keep it that way.
+- **The recommendation is unaffected.** A deterministic question still states
+  its belief through `recommendation.strength` (`confident` is a deterministic
+  read of recorded facts); `DecisionRecommendation` does not change.
+- **The wire is unchanged.** `DecisionQuestionPresentation` carries its own
+  evidence and never carried these fields.
+
+See decision-question-evidence-is-optional.
+
 ## Dependencies
 
 `zod` only. This package stays pure vocabulary — no domain logic, no I/O.

package/src/decisions/__tests__/README.md

@@ -43,7 +43,16 @@ the payload and its **label** is only prose.
   tree and never regenerated. It is the proof that re-expressing a const as a
   factory application left what it accepts unchanged — something neither the
   type checker nor the sampled cases above can see. It is blind to refinements,
-  which stay locked by `schemas.test.ts`.
+  which stay locked by `schemas.test.ts`. Its one intentional edit is
+  decision-question-evidence-is-optional removing `confidence` and `signals`
+  from the question schemas' `required` arrays — a contract change, not drift.
+
+- `question-evidence-optional.test.ts` — measured evidence is optional
+  (decision-question-evidence-is-optional): a deterministic question parses with
+  neither `confidence` nor `signals` and none is invented on the way through; a
+  measured question keeps both; and a source scan of `src/decisions/*.ts` finds
+  no nullish-coalescing default for either field, because readers branch on
+  presence.
 
 - `generic-effect-fixtures.ts` — the compile-time claims of the effect
   parameter (decision-effect-is-a-domain-parameter). A compiled module, not a

package/src/decisions/__tests__/decision-schemas-golden.test.ts

@@ -22,6 +22,12 @@ import * as schemas from "../schemas";
  * fails, the change altered what a schema accepts: fix the code, do not update
  * the golden to make it green.
  *
+ * One deliberate exception, a change to the contract rather than a refactor:
+ * decision-question-evidence-is-optional made a question's `confidence` and
+ * `signals` optional, and exactly those two entries were removed from the
+ * `required` arrays of `DecisionQuestionBaseSchema` and `DecisionQuestionSchema`.
+ * Their property definitions are untouched.
+ *
  * What this cannot see: refinements. `toJSONSchema` drops `superRefine`, so
  * `DecisionQuestionSchema` renders like its base; the cross-field rules stay
  * locked by `schemas.test.ts`.

package/src/decisions/__tests__/fixtures/decision-schemas.golden.json

@@ -854,9 +854,7 @@
       "defaultOptionId",
       "recommendation",
       "multiSelect",
-      "freeFormAllowed",
-      "confidence",
-      "signals"
+      "freeFormAllowed"
     ],
     "additionalProperties": false
   },
@@ -1100,9 +1098,7 @@
       "defaultOptionId",
       "recommendation",
       "multiSelect",
-      "freeFormAllowed",
-      "confidence",
-      "signals"
+      "freeFormAllowed"
     ],
     "additionalProperties": false
   },

package/src/decisions/__tests__/question-evidence-optional.test.ts

@@ -0,0 +1,101 @@
+/**
+ * A question's measured evidence is optional (decision-question-evidence-is-optional).
+ *
+ * Structure inference measures a model confidence and competing signals; a
+ * deterministic derivation — a rule that fired — measures nothing. Requiring
+ * both fields forced the deterministic domain to invent `confidence: 1` and an
+ * empty signals record to share the type, and an unmeasured confidence is not
+ * evidence. These lock the three halves: a deterministic question is valid
+ * without either field and gains neither on the way through the schema, a
+ * measured question loses neither, and nothing in this domain defaults them —
+ * readers branch on presence.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import {
+  DecisionQuestionSchema,
+  type DecisionOption,
+  type DecisionQuestion,
+} from "../index";
+
+const KEEP: DecisionOption = {
+  id: "keep",
+  label: "Keep the unit where it is.",
+  effect: { kind: "none" },
+};
+
+const ARCHIVE: DecisionOption = {
+  id: "archive",
+  label:
+    "Archive the unit; no one has been assigned to it since it was created.",
+  effect: {
+    kind: "archive_unit",
+    unitId: "5b0f6a36-6c1e-4f59-9a55-0c4b3d0f2a11",
+  },
+};
+
+/** A rule fired: the recommendation is a read of recorded facts, not a measurement. */
+const DETERMINISTIC_QUESTION: DecisionQuestion = {
+  id: "empty_unit:5b0f6a36",
+  header: "Empty unit",
+  question: "Should the Facilities unit, which has no members, be archived?",
+  options: [KEEP, ARCHIVE],
+  defaultOptionId: "keep",
+  recommendation: { optionId: "archive", strength: "confident" },
+  multiSelect: false,
+  freeFormAllowed: false,
+};
+
+const MEASURED_QUESTION: DecisionQuestion = {
+  ...DETERMINISTIC_QUESTION,
+  id: "empty_unit:measured",
+  recommendation: { optionId: "archive", strength: "tentative" },
+  confidence: 0.62,
+  signals: {
+    Membership: "No person has listed Facilities as their department.",
+    Documents: "Three documents still name Facilities as their owner.",
+  },
+};
+
+describe("a DecisionQuestion's measured evidence", () => {
+  it("a deterministic question parses with neither confidence nor signals", () => {
+    const parsed = DecisionQuestionSchema.parse(DETERMINISTIC_QUESTION);
+    // Absent, not defaulted: the schema must not invent a measurement.
+    expect("confidence" in parsed).toBe(false);
+    expect("signals" in parsed).toBe(false);
+    expect(parsed.confidence).toBeUndefined();
+    expect(parsed.signals).toBeUndefined();
+  });
+
+  it("a measured question keeps both", () => {
+    const parsed = DecisionQuestionSchema.parse(MEASURED_QUESTION);
+    expect(parsed.confidence).toBe(0.62);
+    expect(parsed.signals).toEqual(MEASURED_QUESTION.signals);
+  });
+
+  it("still bounds a confidence that is present", () => {
+    expect(
+      DecisionQuestionSchema.safeParse({
+        ...MEASURED_QUESTION,
+        confidence: 1.5,
+      }).success,
+    ).toBe(false);
+  });
+
+  it("nothing in decisions defaults the evidence", () => {
+    const dir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const sources = readdirSync(dir).filter((file) => file.endsWith(".ts"));
+    expect(sources.length).toBeGreaterThan(0);
+    const defaulting = /confidence \?\?|signals \?\?/;
+    for (const file of sources) {
+      const found = readFileSync(join(dir, file), "utf8").match(defaulting);
+      expect(
+        found?.[0],
+        `${file} defaults a question's measured evidence; branch on presence instead`,
+      ).toBeUndefined();
+    }
+  });
+});

package/src/decisions/schemas.ts

@@ -94,8 +94,8 @@ export function decisionQuestionBaseSchemaOf<TEffect extends EffectSchema>(
     recommendation: DecisionRecommendationSchema.nullable(),
     multiSelect: z.boolean(),
     freeFormAllowed: z.boolean(),
-    confidence: z.number().min(0).max(1),
-    signals: z.record(z.string(), z.string()),
+    confidence: z.number().min(0).max(1).optional(),
+    signals: z.record(z.string(), z.string()).optional(),
   });
 }
 

package/src/decisions/types.ts

@@ -241,13 +241,21 @@ export interface DecisionQuestion<
    */
   readonly freeFormAllowed: boolean;
   /**
-   * How sure the derivation is of its finding, 0..1. The human-facing reading of
-   * it is {@link DecisionRecommendation.strength}; this number is for ranking and
+   * How sure the derivation is of its finding, 0..1 — PRESENT only when something
+   * was measured. A deterministic derivation (a rule that fired) omits it rather
+   * than claiming 1: an unmeasured confidence is not evidence (contracts ADR
+   * decision-question-evidence-is-optional). Readers branch on presence; nothing
+   * defaults it. The human-facing reading is
+   * {@link DecisionRecommendation.strength}; this number is for ranking and
    * calibration, not for display.
    */
-  readonly confidence: number;
-  /** Each competing signal and a one-line reading of what it says. */
-  readonly signals: Readonly<Record<string, string>>;
+  readonly confidence?: number;
+  /**
+   * Each competing signal and a one-line reading of what it says. PRESENT only
+   * when signals were measured; readers branch on presence, and nothing defaults
+   * it to an empty record.
+   */
+  readonly signals?: Readonly<Record<string, string>>;
 }
 
 /** One answer to one question. */