Propose durable agent state schema 2.0 contract

schemas/fixtures/README.md

@@ -0,0 +1,69 @@
+# Durable agent state review fixtures
+
+All JSON files here are synthetic, language-neutral review data validated with
+the parent [Draft 2020-12 schema](../durable-agent-entity-state.json).
+They are not captured production state, generated serializer snapshots, or
+evidence of Python/.NET 2.0 support.
+
+| Fixture | Provenance and purpose |
+| --- | --- |
+| `shared-durable-agent-state-1.2-python-shape.json` | Reproduced from proposal commit `247bbdd60944d5ac93e79079803aa23e992d0369`. Modeled on parallel Python-shaped 1.2 work, with synthetic future fields and content for preservation review. **Not byte-for-byte output from the current Python serializer.** |
+| `shared-durable-agent-state-2.0.json` | Reproduced from the same proposal commit. Synthetic available success and expired failure receipt, detached from transcript responses; includes unknown mailbox/binding fields. |
+| `shared-durable-agent-state-2.0-pruned.json` | Authored for this contract-only proposal. Empty transcript with available failure, unavailable success, opaque session data, truncation evidence, and whole-entity TTL. Not a migration output. |
+| `shared-durable-agent-state-2.0-lossless.json` | Authored for review feedback. Synthetic developer-role request, verbatim string-form function arguments, URI without invented media type, complete opaque JSON content, explicit structured `false` value, and no binding. |
+
+The source proposal builds on `5de13e8d5dd4b4b76e7360e89ceeb3968a103781`;
+its runtime DTOs, converters, tests, and test-project fixture links are
+deliberately excluded. The corrected `python-shape` filename identifies
+provenance, not a promise of current serializer behavior. There is no fixture
+generator or test-project integration in this PR.
+
+The two reproduced source fixtures are unchanged as JSON values. The example
+bindings are optional runtime-profile data, not a shared binding shape or proof
+of session-fixed effective ownership. Compatible writers preserve them; only a
+runtime relying on a profile validates its identity, version, shape, and policy.
+The original legacy fixture stays valid under the unchanged historical message
+definitions. The expanded lossless fixture is v2-only; its persisted bytes are
+unchanged too.
+
+For `shared-durable-agent-state-2.0.json`, interpret the example at
+`2026-09-10T05:00:05Z`: `corr-2` has an available result and `corr-expired`
+proves completed failure without a payload. After `corr-2`'s expiry a compatible
+poller must report completed-but-result-unavailable even before cleanup.
+
+For `shared-durable-agent-state-2.0-pruned.json`, interpret the example at
+`2026-09-10T06:00:05Z`: `corr-failed` has an available failure payload and
+`corr-pruned` proves completed success without one. Transcript removal did not
+erase either completion. `expirationTimeUtc` is a separate whole-entity deadline,
+not a proposed resolution of tombstone lifetime after entity deletion.
+
+The lossless fixture intentionally contains incomplete function-argument text.
+The exact string must survive; parsing it, completing the JSON, or replacing it
+with an object would lose information. The URI has no `mediaType` to infer. The
+opaque content's nested `$type` and `$runtimeType` are inert JSON, including all
+metadata, not type-activation instructions. `response.value: false` is a present
+structured result; the earlier fixtures omit `value`. Null, zero, and empty
+values have separate [validation cases](../tests/README.md).
+
+The lossless fixture's scalar `ingestedPositions["legacy-producer"] = 3` records
+only highest-seen position. It does not say whether `2` was delivered. None of
+these fixtures defines or infers a gap-preserving workflow receipt set.
+
+The expired receipts retain `outcome`; lookup reports that retained outcome with
+completed-but-result-unavailable, without restoring a payload or reopening
+execution. This contract still requires the corresponding ADR/Python updates.
+No fixture claims that a legacy receipt without authoritative outcome can be
+converted by inventing success or failure. Such a receipt cannot satisfy the
+v2 required-outcome shape without authoritative evidence.
+
+For an identity absent from the receipt maps, the examples show only the
+absence of recorded completion: a separately accepted request may be pending,
+whereas an unrecognized identity remains unknown. No fixture invents an
+admission registry, claims exactly-once external side effects, or authorizes
+schema-version-only migration. The 1.2 and 2.0 examples are independent
+snapshots, not a before/after pair with inferred completion evidence.
+
+Validation must enable Draft 2020-12 and date-time format checking, then check
+the cross-map/time invariants in [the proposal](../README.md). JSON Schema alone
+cannot enforce key equality, atomicity, historical immutability, expiry relative
+to a clock, or compatibility of a deployed reader.

schemas/fixtures/shared-durable-agent-state-1.2-python-shape.json

@@ -0,0 +1,168 @@
+{
+  "schemaVersion": "1.2.0",
+  "data": {
+    "conversationHistory": [
+      {
+        "$type": "request",
+        "correlationId": "corr-python",
+        "createdAt": "2026-07-27T12:34:50+00:00",
+        "messages": [
+          {
+            "role": "user",
+            "messageId": "producer-request-id",
+            "extensionData": {
+              "origin": "python"
+            },
+            "contents": [
+              {
+                "$type": "text",
+                "text": "hello"
+              }
+            ]
+          }
+        ],
+        "extensionData": {
+          "requestFuture": true
+        }
+      },
+      {
+        "$type": "response",
+        "correlationId": "corr-python",
+        "createdAt": "2026-07-27T12:34:51+00:00",
+        "messages": [
+          {
+            "role": "assistant",
+            "authorName": "python-agent",
+            "createdAt": "2026-07-27T12:34:51+00:00",
+            "messageId": "python-metadata-only",
+            "extensionData": {
+              "metadataOrigin": "python"
+            },
+            "contents": []
+          },
+          {
+            "role": "assistant",
+            "contents": [
+              {
+                "$type": "text",
+                "text": "world"
+              }
+            ]
+          },
+          {
+            "role": "assistant",
+            "contents": [
+              {
+                "$type": "reasoning",
+                "text": "private reasoning"
+              }
+            ]
+          },
+          {
+            "role": "assistant",
+            "messageId": "python-unknown-content",
+            "contents": [
+              {
+                "$type": "unknown",
+                "content": {
+                  "$runtimeType": "python-owned-user-field",
+                  "type": "future_python_content",
+                  "payload": "python-value",
+                  "annotations": [
+                    {
+                      "kind": "citation",
+                      "value": "python-ref"
+                    }
+                  ],
+                  "additional_properties": {
+                    "producer": "python"
+                  },
+                  "future_payload": {
+                    "nested": [
+                      1,
+                      2,
+                      3
+                    ]
+                  }
+                }
+              }
+            ]
+          }
+        ],
+        "usage": {
+          "inputTokenCount": 4,
+          "outputTokenCount": 2,
+          "totalTokenCount": 6,
+          "extensionData": {
+            "providerCount": 7,
+            "futureNumeric": 11,
+            "futureString": "seven",
+            "futureObject": {
+              "count": 8
+            },
+            "futureArray": [
+              9
+            ]
+          }
+        }
+      },
+      {
+        "$type": "errorResponse",
+        "correlationId": "corr-error",
+        "createdAt": "2026-07-27T12:34:52+00:00",
+        "messages": [
+          {
+            "role": "assistant",
+            "contents": [
+              {
+                "$type": "error",
+                "message": "failed",
+                "errorCode": "Example"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "$type": "compaction",
+        "createdAt": "2026-07-27T12:34:56.123456+00:00",
+        "messages": [
+          {
+            "role": "assistant",
+            "contents": [
+              {
+                "$type": "text",
+                "text": "summary"
+              }
+            ]
+          }
+        ]
+      }
+    ],
+    "session": {
+      "type": "session",
+      "session_id": "@dafx-agent@session",
+      "state": {
+        "custom": {
+          "value": 1
+        }
+      }
+    },
+    "ingestedPositions": {
+      "input": 0,
+      "writer": 3
+    },
+    "extensionData": {
+      "dataProducer": "python"
+    },
+    "futureDataProperty": {
+      "preserve": true
+    }
+  },
+  "extensionData": {
+    "rootProducer": "interop-fixture"
+  },
+  "futureRootProperty": {
+    "preserve": true
+  }
+}

schemas/fixtures/shared-durable-agent-state-2.0-lossless.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": "2.0.0",
+  "data": {
+    "conversationHistory": [
+      {
+        "$type": "request",
+        "correlationId": "corr-lossless",
+        "messages": [
+          {
+            "role": "developer",
+            "contents": [
+              {
+                "$type": "text",
+                "text": "Preserve the original result."
+              }
+            ]
+          }
+        ]
+      }
+    ],
+    "terminalResults": {
+      "corr-lossless": {
+        "correlationId": "corr-lossless",
+        "outcome": "succeeded",
+        "completedAt": "2026-09-11T10:00:00Z",
+        "response": {
+          "messages": [
+            {
+              "role": "assistant",
+              "contents": [
+                {
+                  "$type": "functionCall",
+                  "callId": "tool-example",
+                  "name": "example_tool",
+                  "arguments": " { \"partial\": "
+                },
+                {
+                  "$type": "uri",
+                  "uri": "https://example.test/media/1"
+                },
+                {
+                  "$type": "unknown",
+                  "content": {
+                    "$type": "example_unmodeled_media",
+                    "$runtimeType": "opaque-data-only",
+                    "bytes": "AQID",
+                    "metadata": {
+                      "presentNull": null,
+                      "empty": [],
+                      "annotations": [
+                        {
+                          "kind": "synthetic"
+                        }
+                      ]
+                    }
+                  }
+                }
+              ]
+            }
+          ],
+          "value": false
+        }
+      }
+    },
+    "completionReceipts": {
+      "corr-lossless": {
+        "correlationId": "corr-lossless",
+        "outcome": "succeeded",
+        "completedAt": "2026-09-11T10:00:00Z",
+        "resultState": "available"
+      }
+    },
+    "ingestedPositions": {
+      "legacy-producer": 3
+    }
+  }
+}

schemas/fixtures/shared-durable-agent-state-2.0-pruned.json

@@ -0,0 +1,59 @@
+{
+  "schemaVersion": "2.0.0",
+  "data": {
+    "conversationHistory": [],
+    "terminalResults": {
+      "corr-failed": {
+        "correlationId": "corr-failed",
+        "outcome": "failed",
+        "completedAt": "2026-09-10T06:00:00Z",
+        "response": {
+          "messages": []
+        },
+        "error": {
+          "code": "example_dependency_unavailable",
+          "message": "The example dependency could not complete the request.",
+          "details": {
+            "synthetic": true
+          }
+        }
+      }
+    },
+    "completionReceipts": {
+      "corr-failed": {
+        "correlationId": "corr-failed",
+        "outcome": "failed",
+        "completedAt": "2026-09-10T06:00:00Z",
+        "resultState": "available"
+      },
+      "corr-pruned": {
+        "correlationId": "corr-pruned",
+        "outcome": "succeeded",
+        "completedAt": "2026-09-09T06:00:00Z",
+        "resultState": "unavailable",
+        "resultExpiresAt": "2026-09-10T06:00:00Z",
+        "resultUnavailableAt": "2026-09-10T06:00:01Z"
+      }
+    },
+    "historyBinding": {
+      "version": 1,
+      "ownerKind": "durableState",
+      "providerKey": "example.local-history.v1"
+    },
+    "session": {
+      "exampleContinuation": {
+        "cursor": "synthetic-cursor",
+        "$runtimeType": "opaque-user-data"
+      }
+    },
+    "expirationTimeUtc": "2026-10-10T06:00:00Z",
+    "ingestedPositions": {
+      "example-producer": 3
+    },
+    "truncation": {
+      "evictedMessageCount": 4,
+      "firstEvictedAt": "2026-09-10T06:00:02Z",
+      "lastEvictedAt": "2026-09-10T06:00:03Z"
+    }
+  }
+}