Define dialect data quality and typed research results

CHANGELOG.md

@@ -7,6 +7,11 @@ here.
 
 ### Added
 
+- Dialect-owned data quality and typed research results (#170, #169): six closed deterministic
+  conversions with recorded failures, three explicit reconciliation modes, presence/type/domain
+  findings surfaced as unknown facts, transformation lineage, typed research result states,
+  versioned acquisition-source profiles, resolved execution settings and retained response bytes.
+  Replay uses retained bytes without calling a model or the web.
 - RFC 0020 limits the later-sibling `limit-exceeded` rule to instances admitted for acquisition;
   admission failures keep their own codes, with a recorded positive vector and negative twin (#213).
 - Document ceiling profiles (#232): default `base` and declared `extended`, a shared

conformance/dialect/README.md

@@ -64,6 +64,20 @@ Runner's first: the Runner calls them "hand-maintained normative data", and says
 The links in the Runner's README are relative to the Runner's repository, and do not resolve here;
 the repository's link check passes over `vectors/` for that reason.
 
+## Companion hand-written cases
+
+[`quality-vectors.json`](quality-vectors.json) and
+[`research-result-vectors.json`](research-result-vectors.json) are specification-authored staged
+cases for the 2026-10-22 amendment, not Runner recordings and not entries in the Runner-derived
+manifest. The first covers every conversion kind, conversion failure, reconciliation mode and
+quality finding, including go-to-market and work-item examples. The second covers the typed result
+contract, every observation state, versioned acquisition-source declarations, resolved execution
+settings and retained bytes. [`research-replay-vector.json`](research-replay-vector.json) is the
+complete public-verifier case: its hand-written expected preparation commits the execution settings
+and decoded retained bytes in lineage, and its changed-bytes twin gives `preparation-differs`.
+Both readers consume these same files; paired reader tests add the empty, missing and one-over-bound
+mutations. No model or web request was made to write any of them.
+
 ## What a vector holds, and the answer a verifier gives
 
 Each vector is a directory. Of its files, a preparation verifier reads:

conformance/dialect/quality-vectors.json

@@ -0,0 +1,40 @@
+{
+  "status": "staged",
+  "cases": [
+    {"id":"gtm-decimal-dot","entry":{"target":"/value","source":"/raw","type":"decimal","required":true,"convert":{"kind":"decimal-from-text","decimalSeparator":".","thousandsSeparator":",","sign":"minus","whitespace":"reject"}},"input":{"raw":"1,234.50"},"expected":"1234.50"},
+    {"id":"decimal-comma","entry":{"target":"/value","source":"/raw","type":"decimal","required":true,"convert":{"kind":"decimal-from-text","decimalSeparator":",","thousandsSeparator":".","sign":"plus-minus","whitespace":"trim"}},"input":{"raw":" +1.234,50 "},"expected":"1234.50"},
+    {"id":"decimal-number","entry":{"target":"/value","source":"/raw","type":"decimal","required":true,"convert":{"kind":"decimal-from-number"}},"input":{"raw":1.25e2},"expected":"125"},
+    {"id":"decimal-number-exponent-shift","entry":{"target":"/value","source":"/raw","type":"decimal","required":true,"convert":{"kind":"decimal-from-number"}},"input":{"raw":0.01e3},"expected":"10"},
+    {"id":"decimal-number-negative-zero","entry":{"target":"/value","source":"/raw","type":"decimal","required":true,"convert":{"kind":"decimal-from-number"}},"input":{"raw":-0e2},"expected":"0"},
+    {"id":"work-item-boolean","entry":{"target":"/value","source":"/raw","type":"boolean","required":true,"convert":{"kind":"boolean-from-text","true":["yes","Y"],"false":["no","N"]}},"input":{"raw":"N"},"expected":false},
+    {"id":"null-string","entry":{"target":"/value","source":"/raw","type":"string","required":true},"input":{"raw":null},"expectedFinding":"wrong-type"},
+    {"id":"null-decimal","entry":{"target":"/value","source":"/raw","type":"decimal","required":true},"input":{"raw":null},"expectedFinding":"wrong-type"},
+    {"id":"null-boolean","entry":{"target":"/value","source":"/raw","type":"boolean","required":true,"convert":{"kind":"boolean-from-text","true":["yes"],"false":["no"]}},"input":{"raw":null},"expectedFinding":"wrong-type"},
+    {"id":"null-date","entry":{"target":"/value","source":"/raw","type":"date","required":true},"input":{"raw":null},"expectedFinding":"wrong-type"},
+    {"id":"missing-preserved","entry":{"target":"/value","source":"/raw","type":"string","required":true,"convert":{"kind":"trim"}},"input":{},"expectedFinding":"missing-required"},
+    {"id":"trim","entry":{"target":"/value","source":"/raw","type":"string","required":true,"convert":{"kind":"trim"}},"input":{"raw":"\u0085value\u3000"},"expected":"value"},
+    {"id":"non-whitespace-bom","entry":{"target":"/value","source":"/raw","type":"string","required":true,"convert":{"kind":"trim"}},"input":{"raw":"\ufeffvalue\ufeff"},"expected":"\ufeffvalue\ufeff"},
+    {"id":"collapse-whitespace","entry":{"target":"/value","source":"/raw","type":"string","required":true,"convert":{"kind":"collapse-whitespace"}},"input":{"raw":"a  b\n c"},"expected":"a b c"},
+    {"id":"date","entry":{"target":"/value","source":"/raw","type":"date","required":true,"convert":{"kind":"date-from-text","format":"DD/MM/YYYY"}},"input":{"raw":"22/10/2026"},"expected":"2026-10-22"},
+    {"id":"date-iso","entry":{"target":"/value","source":"/raw","type":"date","required":true,"convert":{"kind":"date-from-text","format":"YYYY-MM-DD"}},"input":{"raw":"2026-10-22"},"expected":"2026-10-22"},
+    {"id":"date-us","entry":{"target":"/value","source":"/raw","type":"date","required":true,"convert":{"kind":"date-from-text","format":"MM/DD/YYYY"}},"input":{"raw":"10/22/2026"},"expected":"2026-10-22"},
+    {"id":"date-width","entry":{"target":"/value","source":"/raw","type":"date","required":true,"convert":{"kind":"date-from-text","format":"MM/DD/YYYY"}},"input":{"raw":"1/2/2026"},"expectedFinding":"missing-required","expectedFailure":"invalid-encoding"},
+    {"id":"invalid-encoding","entry":{"target":"/value","source":"/raw","type":"date","required":true,"convert":{"kind":"date-from-text","format":"YYYY-MM-DD"}},"input":{"raw":"2026-02-30"},"expectedFinding":"missing-required","expectedFailure":"invalid-encoding"},
+    {"id":"boolean-out-of-domain","entry":{"target":"/value","source":"/raw","type":"boolean","required":true,"convert":{"kind":"boolean-from-text","true":["yes"],"false":["no"]}},"input":{"raw":"maybe"},"expectedFinding":"missing-required","expectedFailure":"out-of-domain"},
+    {"id":"conversion-failure","entry":{"target":"/value","source":"/raw","type":"decimal","required":true,"convert":{"kind":"decimal-from-text","decimalSeparator":".","thousandsSeparator":",","sign":"none","whitespace":"reject"}},"input":{"raw":"not a number"},"expectedFinding":"missing-required","expectedFailure":"not-a-number"},
+    {"id":"malformed-grouping","entry":{"target":"/value","source":"/raw","type":"decimal","required":true,"convert":{"kind":"decimal-from-text","decimalSeparator":".","thousandsSeparator":",","sign":"none","whitespace":"reject"}},"input":{"raw":"1,,2"},"expectedFinding":"missing-required","expectedFailure":"not-a-number"},
+    {"id":"precedence","entry":{"target":"/value","observations":[{"id":"primary","source":"/a"},{"id":"secondary","source":"/b"}],"reconcile":{"mode":"precedence","precedence":["secondary","primary"]},"type":"string","required":true},"input":{"a":"first","b":"second"},"expected":"second","expectedChosen":"secondary"},
+    {"id":"first-present","entry":{"target":"/value","observations":[{"id":"primary","source":"/a"},{"id":"secondary","source":"/b"}],"reconcile":{"mode":"first-present"},"type":"string","required":true},"input":{"b":"second"},"expected":"second","expectedChosen":"secondary"},
+    {"id":"agree","entry":{"target":"/value","observations":[{"id":"one","source":"/a"},{"id":"two","source":"/b"}],"reconcile":{"mode":"agree"},"type":"boolean","required":true},"input":{"a":false,"b":false},"expected":false},
+    {"id":"agree-conflict","entry":{"target":"/value","observations":[{"id":"one","source":"/a"},{"id":"two","source":"/b"}],"reconcile":{"mode":"agree"},"type":"boolean","required":true},"input":{"a":false,"b":true},"expectedFinding":"conflict"},
+    {"id":"domain","entry":{"target":"/value","source":"/raw","type":"decimal","required":true,"domain":{"decimalRange":{"min":"0","max":"10"}}},"input":{"raw":"11"},"expectedFinding":"out-of-domain"},
+    {"id":"reversed-domain","entry":{"target":"/value","source":"/raw","type":"decimal","required":true,"domain":{"decimalRange":{"min":"10","max":"0"}}},"input":{"raw":"5"},"expectedRefusal":"input-malformed"},
+    {"id":"domain-in","entry":{"target":"/value","source":"/raw","type":"string","required":true,"domain":{"in":["open","closed"]}},"input":{"raw":"open"},"expected":"open"},
+    {"id":"wrong-type","entry":{"target":"/value","source":"/raw","type":"boolean","required":true},"input":{"raw":"false"},"expectedFinding":"wrong-type"},
+    {"id":"empty-conversion-rule","entry":{"target":"/value","source":"/raw","type":"boolean","required":true,"convert":{"kind":"boolean-from-text","true":[],"false":["no"]}},"input":{"raw":"no"},"expectedRefusal":"input-malformed"},
+    {"id":"missing-conversion-rule-member","entry":{"target":"/value","source":"/raw","type":"decimal","required":true,"convert":{"kind":"decimal-from-text","decimalSeparator":".","thousandsSeparator":",","whitespace":"reject"}},"input":{"raw":"1"},"expectedRefusal":"input-malformed"},
+    {"id":"observations-over-bound","entry":{"target":"/value","observations":[{"id":"s01","source":"/s01"},{"id":"s02","source":"/s02"},{"id":"s03","source":"/s03"},{"id":"s04","source":"/s04"},{"id":"s05","source":"/s05"},{"id":"s06","source":"/s06"},{"id":"s07","source":"/s07"},{"id":"s08","source":"/s08"},{"id":"s09","source":"/s09"},{"id":"s10","source":"/s10"},{"id":"s11","source":"/s11"},{"id":"s12","source":"/s12"},{"id":"s13","source":"/s13"},{"id":"s14","source":"/s14"},{"id":"s15","source":"/s15"},{"id":"s16","source":"/s16"},{"id":"s17","source":"/s17"}],"reconcile":{"mode":"first-present"},"type":"string","required":true},"input":{},"expectedRefusal":"input-over-bound"},
+    {"id":"unknown-conversion","entry":{"target":"/value","source":"/raw","type":"string","required":true,"convert":{"kind":"script"}},"input":{"raw":"x"},"expectedRefusal":"input-malformed"},
+    {"id":"last-writer-wins","entry":{"target":"/value","observations":[{"id":"one","source":"/a"},{"id":"two","source":"/b"}],"reconcile":{"mode":"last-writer-wins"},"type":"string","required":true},"input":{"a":"x","b":"y"},"expectedRefusal":"input-malformed"}
+  ]
+}

conformance/dialect/research-replay-vector.json

@@ -0,0 +1,103 @@
+{
+  "status": "staged",
+  "dialect": {
+    "version": 3,
+    "case": {"facts": [], "evidence": []},
+    "sources": [{
+      "name": "research",
+      "kind": "research",
+      "profile": "assistant",
+      "profileDigest": "sha256:4212594e06b8c421c1a8de92ac5a1260b1d0e05cdca027bd65216c20be8b4540",
+      "webProfiles": {},
+      "maxAge": 300,
+      "question": "Summarize the retained response.",
+      "constraints": {"synthetic": true},
+      "model": "synthetic-research-model-1",
+      "evidence": ["Use only the retained response."],
+      "results": [{"id":"summary","type":"string","required":true,"description":"The retained summary.","cardinality":"one"}],
+      "acquisitionSources": [{"profile":"public-pages","version":"1","purpose":"discovery","scope":{"origins":["https://example.invalid"]},"freshness":86400}],
+      "capabilities": ["answer"],
+      "read": {"copy":{"facts":[{"target":"/research/state","source":"/results/summary/status","type":"string","required":true,"convert":{"kind":"trim"}}],"evidence":[]}}
+    }],
+    "admits":{"facts":{"/research/state":["generated"]}}
+  },
+  "case": {},
+  "acquisitions": {
+    "research": {"response":{"result":{
+      "results":{"summary":{"status":"missing","cites":[],"reason":"The retained response contains no summary."}},
+      "responses":[],
+      "execution":{
+        "resolvedSettings":{"model":"synthetic-research-model-1","profile":"assistant","version":"1","settings":{"temperature":"0"}},
+        "retainedBytes":[{"mediaType":"application/json","base64":"eyJzdGF0dXMiOiJtaXNzaW5nIn0="}]
+      }
+    }}}
+  },
+  "profiles": [{
+    "id":"assistant",
+    "publicKey":"c41a130f46f6427931f1fe90bf0702de9980108fcef8f845722ddab4afda3511",
+    "class":"generated",
+    "source":"web-search",
+    "authority":"stand-in",
+    "shape":"http",
+    "adapter":{"name":"adapter-sources","version":"stand-in","digest":"sha256:e05658804f621bd96ba149df689a8410a625573ff9bc1cf2376732e67d3dc061"},
+    "endpoint":"https://127.0.0.1:37399/answers",
+    "research":{"capabilities":["answer","search"],"model":"synthetic-research-model-1"}
+  }],
+  "verifiedAt": "2026-10-22T12:00:00Z",
+  "tamperedBase64": "eyJzdGF0dXMiOiJwcmVzZW50In0=",
+  "expectedTampered": "preparation-differs",
+  "preparation": {
+    "version": 3,
+    "verifiedAt": "2026-10-22T12:00:00Z",
+    "mappingDigest": "sha256:def3cc8511ce213d094ce04a4edd0961f0a2f2ed8731f97bc9139b2cefbb4250",
+    "verification": "verified acquisitions; session sealing and input truth are not established",
+    "cites": [],
+    "lineage": [{
+      "source": "research",
+      "kind": "fact",
+      "target": "/research/state",
+      "class": "generated",
+      "generatedInfluence": true,
+      "present": true,
+      "status": "resolved",
+      "reason": "copied",
+      "basis": ["/results/summary/status"],
+      "readDigest": "sha256:0e7ce757bc774f0f3bd37c54c82dd5bd2b84e2572bc128e9134f29362a499898",
+      "candidateFrom": ["/results/summary/status"],
+      "receipts": [],
+      "researchExecution": {
+        "resolvedSettings":{"model":"synthetic-research-model-1","profile":"assistant","version":"1","settings":{"temperature":"0"}},
+        "retainedBytes":[{"mediaType":"application/json","digest":"sha256:e0d52d700598d4fcbac5ac5350694f541f89510c7ca61774cad9c1742f031fa5"}]
+      },
+      "transformation": {
+        "applications":[{"id":"source","source":"/results/summary/status","state":"present","sourceText":"\"missing\"","rule":{"kind":"trim"},"result":"missing"}],
+        "findings":[]
+      }
+    }],
+    "outcomes": [
+      {
+        "name":"case",
+        "parameters":{"runAt":"2026-10-22T12:00:00Z"},
+        "claim":{"facts":{},"evidenceAvailability":{},"acquisitionStatus":"resolved","reason":"copied","basis":[]},
+        "status":"resolved",
+        "reason":"copied"
+      },
+      {
+        "name":"research",
+        "parameters":{"runAt":"2026-10-22T12:00:00Z"},
+        "claim":{"facts":{"research":{"state":"missing"}},"evidenceAvailability":{},"acquisitionStatus":"resolved","reason":"copied","basis":["/results/summary/status"]},
+        "status":"resolved",
+        "reason":"copied",
+        "arguments":{
+          "question":"Summarize the retained response.",
+          "constraints":{"synthetic":true},
+          "model":"synthetic-research-model-1",
+          "evidence":["Use only the retained response."],
+          "results":[{"id":"summary","type":"string","required":true,"description":"The retained summary.","cardinality":"one"}],
+          "capabilities":["answer"],
+          "acquisitionSources":[{"profile":"public-pages","version":"1","purpose":"discovery","scope":{"origins":["https://example.invalid"]},"freshness":86400}]
+        }
+      }
+    ]
+  }
+}

conformance/dialect/research-result-vectors.json

@@ -0,0 +1,63 @@
+{
+  "status": "staged",
+  "dialect": {
+    "version": 3,
+    "case": {"facts": [], "evidence": []},
+    "sources": [{
+      "name": "research",
+      "kind": "research",
+      "profile": "generated",
+      "profileDigest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+      "webProfiles": {},
+      "maxAge": 300,
+      "question": "Summarize the retained material.",
+      "constraints": {},
+      "model": "portable-model",
+      "evidence": ["Retain the response bytes."],
+      "results": [
+        {"id":"summary","type":"string","required":true,"description":"A concise summary.","cardinality":"one"},
+        {"id":"score","type":"decimal","required":true,"description":"An exact score.","cardinality":"one"},
+        {"id":"flags","type":"boolean","required":true,"description":"Boolean flags.","cardinality":"many"},
+        {"id":"tags","type":"string-list","required":true,"description":"Ordered tags.","cardinality":"many"},
+        {"id":"decision","type":"boolean","required":true,"description":"Conflicting decisions.","cardinality":"one"},
+        {"id":"access","type":"string","required":true,"description":"An inaccessible observation.","cardinality":"one"},
+        {"id":"old","type":"string","required":true,"description":"A stale observation.","cardinality":"one"}
+      ],
+      "acquisitionSources": [{"profile":"public-pages","version":"1","purpose":"discovery","scope":{"origins":["https://example.invalid"]},"freshness":86400}],
+      "capabilities": ["answer"],
+      "read": {"copy":{"facts":[{"target":"/research/state","source":"/results/summary/status","type":"string","required":true,"convert":{"kind":"trim"}}],"evidence":[]}}
+    }]
+  },
+  "cases": [
+    {
+      "id": "requested-observation-and-retained-replay",
+      "record": {
+        "results":{
+          "summary":{"status":"missing","cites":[],"reason":"No retained page answered the request."},
+          "score":{"status":"present","cites":[0],"value":"1.00"},
+          "flags":{"status":"present","cites":[0],"value":[false,true]},
+          "tags":{"status":"present","cites":[0],"value":[["reviewed","portable"],["public"]]},
+          "decision":{"status":"conflicting","cites":[],"values":[{"value":false,"cites":[0]},{"value":true,"cites":[0]}]},
+          "access":{"status":"inaccessible","cites":[],"reason":"The source denied access."},
+          "old":{"status":"stale","cites":[],"reason":"The observation exceeded its freshness declaration."}
+        },
+        "responses":[{"profile":{"id":"generated","digest":"sha256:0000000000000000000000000000000000000000000000000000000000000000"},"request":{},"result":{},"receipt":{},"salts":{"args":"0000000000000000000000000000000000000000000000000000000000000000"}}],
+        "execution":{"resolvedSettings":{"model":"resolved-model-v1","profile":"generated-default","version":"1","settings":{"temperature":"0"}},"retainedBytes":[{"mediaType":"application/json","base64":"e30="}]}
+      },
+      "expected": "accepted"
+    },
+    {
+      "id": "result-outside-contract",
+      "record": {
+        "results":{"summary":{"status":"missing","cites":[],"reason":"No answer."},"undeclared":{"status":"missing","cites":[],"reason":"Not requested."}},
+        "responses":[],
+        "execution":{"resolvedSettings":{"model":"resolved-model-v1","profile":"generated-default","version":"1","settings":{}},"retainedBytes":[]}
+      },
+      "expected": "input-malformed"
+    }
+  ],
+  "mutations": [
+    {"id":"typed-result-refuses-found","field":"score","status":"found","cites":[0],"value":"1.00","expected":"input-malformed"},
+    {"id":"typed-result-refuses-not-found","field":"score","status":"not-found","expected":"input-malformed"}
+  ]
+}