matelab-python-sdk 0.1.0a19__tar.gz → 0.1.0a20__tar.gz

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/CHANGELOG.md

@@ -3,6 +3,18 @@
 This file records release-to-release changes and migration impact. It is not the authority for the current interface;
 see [README.md](README.md) for current behavior and [AGENTS.md](AGENTS.md) for maintenance policy.
 
+## 0.1.0a20 - 2026-08-24
+
+- Adopts immutable `matelab-spec v0.4.3` at commit `7965ac9803505ae35dc5ce36f52afc3c2c133c45` and OpenAPI
+  SHA-256 `6576812dd13f92ad58131f4edb8dc919d1b1fe0f19a695c2d25fbe6d13a8445b`, aligned with Provider evidence
+  `a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27`.
+- Breaking: tightens record readback to one canonical attachment object or `null` per table file cell, removing the
+  obsolete attachment-array compatibility path. Template decoding now accepts nullable JSON-code data and preserves
+  empty-string number/boolean cells alongside their scalar and null forms.
+- Records PVD-046 while keeping `templates.save_content()` deliberately narrower than the Provider: the request remains
+  a canonical module list, and every table file cell remains one canonical attachment object or `null`, never an
+  arbitrary or multi-attachment array.
+
 ## 0.1.0a19 - 2026-08-23
 
 - Re-adopts the force-rewritten `matelab-spec v0.4.2` at commit

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a19
+Version: 0.1.0a20
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -35,10 +35,10 @@ This README describes the current SDK interface, integration semantics, examples
 [AGENTS.md](AGENTS.md) for durable maintenance rules, and `docs/operation-coverage.yaml` for the machine-readable
 operation inventory.
 
-The current alpha is `0.1.0a19`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a20`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
-The SDK is pinned to the rewritten `matelab-spec v0.4.2` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.4.3` Contract Release. The sole release pin is
 `contracts/matelab-integration-v1.lock.json`, which records
 the source tag, commit, OpenAPI path, local snapshot path, and SHA-256.
 
@@ -64,7 +64,7 @@ To test the same artifact a downstream Consumer will install, build and install
 
 ```bash
 uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.1.0a19-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a20-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -121,7 +121,7 @@ success code it does not allow raises `MatelabProtocolError` rather than assigni
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies, top-level `msg`,
 legacy `errmsg`, opaque `errs`, uncontracted debug fields, and request payloads are not attached to exceptions because
 Provider-authored diagnostics may contain stack traces, credentials, or submitted values.
-The pinned v0.4.2 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record opaque array/object
+The pinned v0.4.3 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record opaque array/object
 containers and insufficient evidence for requiredness, cardinality, or exclusion from other codes. The SDK
 therefore keeps those diagnostics wire-only and does not expose `errs` as stable public metadata. A typed detail
 interface remains blocked until a future Contract release can define one from stronger Provider evidence. `retryable`
@@ -348,7 +348,9 @@ await client.records.update(
 
 For a files occurrence, `caption=None` preserves the observed string caption (an observed null caption normalizes to
 the required empty string). Table replacement requires exactly one current attachment in the selected cell and does
-not accept a caption. Both forms require the replacement hash to differ from the current occurrence.
+not accept a caption. Record reads likewise accept only one canonical attachment object or `null` in a table file cell;
+an attachment array violates the pinned response contract. Both replacement forms require the replacement hash to
+differ from the current occurrence.
 
 All record attachment intents reject handles from another notebook or authenticated uploader, duplicate use within one
 finalization request, and raw Provider attachment references. Row/index-based operations use an immediate SDK read and
@@ -500,9 +502,12 @@ await client.templates.save_content(template, modules)
 `TemplateModule.data_present` distinguishes a missing `data` property from an explicit null value, while
 `attributes` prevents additive canonical properties from being dropped during a read/save cycle. The SDK does not
 synthesize frontend editor UIDs, layout widths, rows, folders, option encoding, or a fixed set of display module
-types. The Provider supports only whole-content replacement and has no atomic patch or compare-and-swap operation
-(PCG-007), so
-a read-modify-save sequence can overwrite a concurrent change.
+types. A JSON-language code module with style metadata may return its JSON string or explicit `null`; number and boolean
+table cells preserve the Provider's empty string as distinct from scalar and `null` values. The Provider accepts some
+non-canonical module roots and arbitrary table file arrays, but the SDK does not expose that behavior: saved content
+must remain a canonical module list, and a table file cell must be one canonical attachment object or `null` (PVD-046).
+The Provider supports only whole-content replacement and has no atomic patch or compare-and-swap operation (PCG-007),
+so a read-modify-save sequence can overwrite a concurrent change.
 
 The market result retains the Provider's `total_count` and derives `has_more` without echoing the caller's page
 arguments; it does not claim a stable order or continuation token. Template reads remain experimental
@@ -912,6 +917,6 @@ uv run python scripts/check_release.py dist/release/*.whl dist/release/*.tar.gz
 ```
 
 Rebuilding the same commit with the same locked environment and `SOURCE_DATE_EPOCH` must produce
-byte-identical wheel and source distribution hashes. The release is bound to the rewritten `matelab-spec v0.4.2`,
-commit `1a4b77721d782fccd2b1f26bcc16a7d876347686`, and OpenAPI SHA-256
-`1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b`.
+byte-identical wheel and source distribution hashes. The release is bound to immutable `matelab-spec v0.4.3`, commit
+`7965ac9803505ae35dc5ce36f52afc3c2c133c45`, and OpenAPI SHA-256
+`6576812dd13f92ad58131f4edb8dc919d1b1fe0f19a695c2d25fbe6d13a8445b`.

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/README.md

@@ -7,10 +7,10 @@ This README describes the current SDK interface, integration semantics, examples
 [AGENTS.md](AGENTS.md) for durable maintenance rules, and `docs/operation-coverage.yaml` for the machine-readable
 operation inventory.
 
-The current alpha is `0.1.0a19`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a20`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
-The SDK is pinned to the rewritten `matelab-spec v0.4.2` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.4.3` Contract Release. The sole release pin is
 `contracts/matelab-integration-v1.lock.json`, which records
 the source tag, commit, OpenAPI path, local snapshot path, and SHA-256.
 
@@ -36,7 +36,7 @@ To test the same artifact a downstream Consumer will install, build and install
 
 ```bash
 uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.1.0a19-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a20-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -93,7 +93,7 @@ success code it does not allow raises `MatelabProtocolError` rather than assigni
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies, top-level `msg`,
 legacy `errmsg`, opaque `errs`, uncontracted debug fields, and request payloads are not attached to exceptions because
 Provider-authored diagnostics may contain stack traces, credentials, or submitted values.
-The pinned v0.4.2 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record opaque array/object
+The pinned v0.4.3 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record opaque array/object
 containers and insufficient evidence for requiredness, cardinality, or exclusion from other codes. The SDK
 therefore keeps those diagnostics wire-only and does not expose `errs` as stable public metadata. A typed detail
 interface remains blocked until a future Contract release can define one from stronger Provider evidence. `retryable`
@@ -320,7 +320,9 @@ await client.records.update(
 
 For a files occurrence, `caption=None` preserves the observed string caption (an observed null caption normalizes to
 the required empty string). Table replacement requires exactly one current attachment in the selected cell and does
-not accept a caption. Both forms require the replacement hash to differ from the current occurrence.
+not accept a caption. Record reads likewise accept only one canonical attachment object or `null` in a table file cell;
+an attachment array violates the pinned response contract. Both replacement forms require the replacement hash to
+differ from the current occurrence.
 
 All record attachment intents reject handles from another notebook or authenticated uploader, duplicate use within one
 finalization request, and raw Provider attachment references. Row/index-based operations use an immediate SDK read and
@@ -472,9 +474,12 @@ await client.templates.save_content(template, modules)
 `TemplateModule.data_present` distinguishes a missing `data` property from an explicit null value, while
 `attributes` prevents additive canonical properties from being dropped during a read/save cycle. The SDK does not
 synthesize frontend editor UIDs, layout widths, rows, folders, option encoding, or a fixed set of display module
-types. The Provider supports only whole-content replacement and has no atomic patch or compare-and-swap operation
-(PCG-007), so
-a read-modify-save sequence can overwrite a concurrent change.
+types. A JSON-language code module with style metadata may return its JSON string or explicit `null`; number and boolean
+table cells preserve the Provider's empty string as distinct from scalar and `null` values. The Provider accepts some
+non-canonical module roots and arbitrary table file arrays, but the SDK does not expose that behavior: saved content
+must remain a canonical module list, and a table file cell must be one canonical attachment object or `null` (PVD-046).
+The Provider supports only whole-content replacement and has no atomic patch or compare-and-swap operation (PCG-007),
+so a read-modify-save sequence can overwrite a concurrent change.
 
 The market result retains the Provider's `total_count` and derives `has_more` without echoing the caller's page
 arguments; it does not claim a stable order or continuation token. Template reads remain experimental
@@ -884,6 +889,6 @@ uv run python scripts/check_release.py dist/release/*.whl dist/release/*.tar.gz
 ```
 
 Rebuilding the same commit with the same locked environment and `SOURCE_DATE_EPOCH` must produce
-byte-identical wheel and source distribution hashes. The release is bound to the rewritten `matelab-spec v0.4.2`,
-commit `1a4b77721d782fccd2b1f26bcc16a7d876347686`, and OpenAPI SHA-256
-`1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b`.
+byte-identical wheel and source distribution hashes. The release is bound to immutable `matelab-spec v0.4.3`, commit
+`7965ac9803505ae35dc5ce36f52afc3c2c133c45`, and OpenAPI SHA-256
+`6576812dd13f92ad58131f4edb8dc919d1b1fe0f19a695c2d25fbe6d13a8445b`.

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/contracts/matelab-integration-v1.lock.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v0.4.2",
-    "commit": "1a4b77721d782fccd2b1f26bcc16a7d876347686"
+    "tag": "v0.4.3",
+    "commit": "7965ac9803505ae35dc5ce36f52afc3c2c133c45"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b"
+    "sha256": "6576812dd13f92ad58131f4edb8dc919d1b1fe0f19a695c2d25fbe6d13a8445b"
   }
 }

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/contracts/matelab-integration-v1.openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Matelab Integration Contract
-  version: 0.4.2
+  version: 0.4.3
   description: |
     Current PHP wire contract for generating SDKs against the selected
     `matelab-server` Provider version.
@@ -50,6 +50,10 @@ info:
       - {operationId: extractLiteratureMetadata, change: doi-format-validated-before-extraction}
       - {operationId: searchRecordData, change: encrypted-records-excluded}
       - {operationId: updateRecordData, change: files-folder-path-removed-from-callable-shape}
+      - {operationId: readRecord, change: table-file-cell-readback-modeled-as-attachment-object-or-null}
+      - {operationId: readTemplateContent, change: json-code-null-readback-accepted}
+      - {operationId: saveTemplateContent, change: empty-number-and-boolean-cells-preserved}
+      - {operationId: saveTemplateContent, change: noncanonical-module-structures-contract-contained}
   x-consumer-evidence:
     - repository: /home/tnzhu/projects/matelab-mcp
       commit: 94a129b2df0ef0fbcf179c10550fb7c9a5dd2e6f
@@ -827,6 +831,7 @@ paths:
       operationId: saveTemplateContent
       tags: [Templates]
       summary: Replace canonical modules for an owned template
+      x-known-provider-issues: [PVD-046]
       security: [{bearerAuth: []}]
       requestBody:
         required: true
@@ -2541,6 +2546,19 @@ paths:
                         name: Notes
                         uid: module-example
                         data: Sanitized content
+                      - type: table
+                        name: Measurements
+                        uid: table-example
+                        rows: [row-example]
+                        data:
+                          - type: file
+                            name: Evidence
+                            uid: column-example
+                            data:
+                              - filename: evidence.txt
+                                hash: 74034daeef860e12596c34f7e83703e668d578f4a85e72ec1645117223d4e6a7
+                                size: 26
+                                timestamp: 1767946200000
                     template_id: 8
                     datetime_modify: 1767946200000
                     username: Example User
@@ -4914,7 +4932,7 @@ components:
             required: [data]
             properties:
               data:
-                type: string
+                type: [string, "null"]
                 contentMediaType: application/json
       additionalProperties: true
     TemplateTableColumn:
@@ -4949,6 +4967,7 @@ components:
                   oneOf:
                     - {type: number}
                     - {type: string, pattern: '^[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$'}
+                    - {type: string, const: ""}
                     - {type: "null"}
         - if:
             properties: {type: {const: bool}}
@@ -4957,7 +4976,11 @@ components:
             properties:
               data:
                 type: array
-                items: {type: [boolean, "null"]}
+                items:
+                  oneOf:
+                    - {type: boolean}
+                    - {type: string, const: ""}
+                    - {type: "null"}
         - if:
             properties: {type: {const: file}}
             required: [type]
@@ -4967,9 +4990,25 @@ components:
                 type: array
                 items:
                   oneOf:
-                    - {type: array}
+                    - {$ref: "#/components/schemas/RecordAttachment"}
                     - {type: "null"}
       additionalProperties: true
+    RecordAttachment:
+      type: object
+      required: [filename, hash, size, timestamp]
+      properties:
+        filename:
+          type: string
+          description: Original filename; the Provider's canonical empty attachment uses an empty string.
+        hash:
+          type: string
+          pattern: "^(?:[0-9a-f]{64})?$"
+          description: SHA-256 digest, or an empty string in the Provider's canonical empty attachment.
+        size: {type: integer, minimum: 0}
+        timestamp:
+          type: integer
+          minimum: 1
+          description: Provider-generated Unix timestamp in milliseconds.
     TemplateFormItem:
       type: object
       required: [name]

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/docs/operation-coverage.yaml

@@ -3,7 +3,7 @@
 schema_version: 1
 contract:
   line: integration-v1
-  release: v0.4.2
+  release: v0.4.3
   operation_count: 71
 
 operations:
@@ -133,7 +133,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.templates.save_content
-    known_issues: [PCG-007]
+    known_issues: [PCG-007, PVD-046]
 
   - operation_id: copyTemplate
     method: POST

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.1.0a19"
+version = "0.1.0a20"
 description = "Reusable async Python client for the Matelab Integration Contract"
 readme = "README.md"
 requires-python = ">=3.11"

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/src/matelab/_generated/models.py

@@ -11,7 +11,7 @@ from pydantic import ConfigDict, Field, RootModel, SecretStr, StrictBool, Strict
 
 from matelab._wire_validation import WireModel
 
-OPENAPI_INFO_VERSION = "0.4.2"
+OPENAPI_INFO_VERSION = "0.4.3"
 
 
 class ResponseEnvelope(WireModel):
@@ -638,7 +638,11 @@ class SaveTemplateContentRequest(WireModel):
                                     "then": {
                                         "required": ["data"],
                                         "properties": {
-                                            "data": {"type": "string", "contentMediaType": "application/json"}
+                                            "data": {
+                                                "type": ["string", "null"],
+                                                "contentMediaType": "application/json",
+                                                "nullable": True,
+                                            }
                                         },
                                     },
                                 },
@@ -686,6 +690,7 @@ class SaveTemplateContentRequest(WireModel):
                                                             "type": "string",
                                                             "pattern": "^[+-]?(?:[0-9]+(?:\\.[0-9]*)?|\\.[0-9]+)(?:[eE][+-]?[0-9]+)?$",
                                                         },
+                                                        {"type": "string", "const": ""},
                                                         {"type": "null"},
                                                     ]
                                                 },
@@ -699,7 +704,13 @@ class SaveTemplateContentRequest(WireModel):
                                         "properties": {
                                             "data": {
                                                 "type": "array",
-                                                "items": {"type": ["boolean", "null"], "nullable": True},
+                                                "items": {
+                                                    "oneOf": [
+                                                        {"type": "boolean"},
+                                                        {"type": "string", "const": ""},
+                                                        {"type": "null"},
+                                                    ]
+                                                },
                                             }
                                         }
                                     },
@@ -710,7 +721,9 @@ class SaveTemplateContentRequest(WireModel):
                                         "properties": {
                                             "data": {
                                                 "type": "array",
-                                                "items": {"oneOf": [{"type": "array"}, {"type": "null"}]},
+                                                "items": {
+                                                    "oneOf": [{"$ref": "#/$defs/RecordAttachment"}, {"type": "null"}]
+                                                },
                                             }
                                         }
                                     },
@@ -718,6 +731,27 @@ class SaveTemplateContentRequest(WireModel):
                             ],
                             "additionalProperties": True,
                         },
+                        "RecordAttachment": {
+                            "type": "object",
+                            "required": ["filename", "hash", "size", "timestamp"],
+                            "properties": {
+                                "filename": {
+                                    "type": "string",
+                                    "description": "Original filename; the Provider's canonical empty attachment uses an empty string.",
+                                },
+                                "hash": {
+                                    "type": "string",
+                                    "pattern": "^(?:[0-9a-f]{64})?$",
+                                    "description": "SHA-256 digest, or an empty string in the Provider's canonical empty attachment.",
+                                },
+                                "size": {"type": "integer", "minimum": 0},
+                                "timestamp": {
+                                    "type": "integer",
+                                    "minimum": 1,
+                                    "description": "Provider-generated Unix timestamp in milliseconds.",
+                                },
+                            },
+                        },
                         "TemplateFormItem": {
                             "type": "object",
                             "required": ["name"],
@@ -789,7 +823,13 @@ class TemplateModule(WireModel):
                         },
                         "then": {
                             "required": ["data"],
-                            "properties": {"data": {"type": "string", "contentMediaType": "application/json"}},
+                            "properties": {
+                                "data": {
+                                    "type": ["string", "null"],
+                                    "contentMediaType": "application/json",
+                                    "nullable": True,
+                                }
+                            },
                         },
                     },
                 ],
@@ -835,6 +875,7 @@ class TemplateModule(WireModel):
                                                         "type": "string",
                                                         "pattern": "^[+-]?(?:[0-9]+(?:\\.[0-9]*)?|\\.[0-9]+)(?:[eE][+-]?[0-9]+)?$",
                                                     },
+                                                    {"type": "string", "const": ""},
                                                     {"type": "null"},
                                                 ]
                                             },
@@ -848,7 +889,13 @@ class TemplateModule(WireModel):
                                     "properties": {
                                         "data": {
                                             "type": "array",
-                                            "items": {"type": ["boolean", "null"], "nullable": True},
+                                            "items": {
+                                                "oneOf": [
+                                                    {"type": "boolean"},
+                                                    {"type": "string", "const": ""},
+                                                    {"type": "null"},
+                                                ]
+                                            },
                                         }
                                     }
                                 },
@@ -859,7 +906,9 @@ class TemplateModule(WireModel):
                                     "properties": {
                                         "data": {
                                             "type": "array",
-                                            "items": {"oneOf": [{"type": "array"}, {"type": "null"}]},
+                                            "items": {
+                                                "oneOf": [{"$ref": "#/$defs/RecordAttachment"}, {"type": "null"}]
+                                            },
                                         }
                                     }
                                 },
@@ -867,6 +916,27 @@ class TemplateModule(WireModel):
                         ],
                         "additionalProperties": True,
                     },
+                    "RecordAttachment": {
+                        "type": "object",
+                        "required": ["filename", "hash", "size", "timestamp"],
+                        "properties": {
+                            "filename": {
+                                "type": "string",
+                                "description": "Original filename; the Provider's canonical empty attachment uses an empty string.",
+                            },
+                            "hash": {
+                                "type": "string",
+                                "pattern": "^(?:[0-9a-f]{64})?$",
+                                "description": "SHA-256 digest, or an empty string in the Provider's canonical empty attachment.",
+                            },
+                            "size": {"type": "integer", "minimum": 0},
+                            "timestamp": {
+                                "type": "integer",
+                                "minimum": 1,
+                                "description": "Provider-generated Unix timestamp in milliseconds.",
+                            },
+                        },
+                    },
                     "TemplateFormItem": {
                         "type": "object",
                         "required": ["name"],
@@ -929,6 +999,7 @@ class TemplateTableColumn(WireModel):
                                                 "type": "string",
                                                 "pattern": "^[+-]?(?:[0-9]+(?:\\.[0-9]*)?|\\.[0-9]+)(?:[eE][+-]?[0-9]+)?$",
                                             },
+                                            {"type": "string", "const": ""},
                                             {"type": "null"},
                                         ]
                                     },
@@ -940,7 +1011,16 @@ class TemplateTableColumn(WireModel):
                         "if": {"properties": {"type": {"const": "bool"}}, "required": ["type"]},
                         "then": {
                             "properties": {
-                                "data": {"type": "array", "items": {"type": ["boolean", "null"], "nullable": True}}
+                                "data": {
+                                    "type": "array",
+                                    "items": {
+                                        "oneOf": [
+                                            {"type": "boolean"},
+                                            {"type": "string", "const": ""},
+                                            {"type": "null"},
+                                        ]
+                                    },
+                                }
                             }
                         },
                     },
@@ -948,11 +1028,37 @@ class TemplateTableColumn(WireModel):
                         "if": {"properties": {"type": {"const": "file"}}, "required": ["type"]},
                         "then": {
                             "properties": {
-                                "data": {"type": "array", "items": {"oneOf": [{"type": "array"}, {"type": "null"}]}}
+                                "data": {
+                                    "type": "array",
+                                    "items": {"oneOf": [{"$ref": "#/$defs/RecordAttachment"}, {"type": "null"}]},
+                                }
                             }
                         },
                     },
-                ]
+                ],
+                "$defs": {
+                    "RecordAttachment": {
+                        "type": "object",
+                        "required": ["filename", "hash", "size", "timestamp"],
+                        "properties": {
+                            "filename": {
+                                "type": "string",
+                                "description": "Original filename; the Provider's canonical empty attachment uses an empty string.",
+                            },
+                            "hash": {
+                                "type": "string",
+                                "pattern": "^(?:[0-9a-f]{64})?$",
+                                "description": "SHA-256 digest, or an empty string in the Provider's canonical empty attachment.",
+                            },
+                            "size": {"type": "integer", "minimum": 0},
+                            "timestamp": {
+                                "type": "integer",
+                                "minimum": 1,
+                                "description": "Provider-generated Unix timestamp in milliseconds.",
+                            },
+                        },
+                    }
+                },
             }
         },
     )
@@ -964,6 +1070,22 @@ class TemplateTableColumn(WireModel):
     data: list[Any]
 
 
+class RecordAttachment(WireModel):
+    filename: str
+    """
+    Original filename; the Provider's canonical empty attachment uses an empty string.
+    """
+    hash: Annotated[str, Field(pattern="^(?:[0-9a-f]{64})?$")]
+    """
+    SHA-256 digest, or an empty string in the Provider's canonical empty attachment.
+    """
+    size: Annotated[StrictInt, Field(ge=0)]
+    timestamp: Annotated[StrictInt, Field(ge=1)]
+    """
+    Provider-generated Unix timestamp in milliseconds.
+    """
+
+
 class TemplateFormItem(WireModel):
     model_config = ConfigDict(extra="allow")
     name: Annotated[str, Field(min_length=1, pattern=".*[^0-9.\\-+eE ].*")]

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/src/matelab/domains/records.py

@@ -722,13 +722,7 @@ def _record_attachment_refs(
                 ):
                     continue
                 for position, value in enumerate(field_values):
-                    if kind == "table_file" and isinstance(value, list):
-                        for attachment in value:
-                            add_structured(
-                                attachment, kind=kind, module=module_name, field_name=field_name, position=position
-                            )
-                    else:
-                        add_structured(value, kind=kind, module=module_name, field_name=field_name, position=position)
+                    add_structured(value, kind=kind, module=module_name, field_name=field_name, position=position)
         elif module_type in {"files", "images"} and isinstance(values, list):
             file_kind = "files_module" if module_type == "files" else "images_module"
             for position, value in enumerate(values):

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/tests/test_generation.py

@@ -108,6 +108,127 @@ def test_generated_response_preserves_required_nullable_fields() -> None:
     assert response.keywords is None
 
 
+def _item_view_payload(modules: list[object]) -> dict[str, object]:
+    return {
+        "code": 0,
+        "msg": "",
+        "errcode": 0,
+        "errmsg": "",
+        "title": None,
+        "keywords": None,
+        "modules": modules,
+        "template_id": None,
+        "datetime_modify": 1,
+        "username": None,
+        "modify_log": [],
+        "uid": None,
+        "current_version": 0,
+        "item_id": 1,
+        "datetime_locked": 0,
+        "locked": False,
+        "signs": [],
+        "signed": False,
+        "owner": False,
+        "eln_text": None,
+        "eln_server": "localhost",
+        "eln_id": 1,
+        "editable": False,
+        "keyword_eln": [],
+        "pdf_enable": False,
+        "template_show": "",
+        "template_text": "",
+        "template_intro": "",
+    }
+
+
+def _record_attachment() -> dict[str, object]:
+    return {"filename": "evidence.txt", "hash": "0" * 64, "size": 26, "timestamp": 1_767_946_200_000}
+
+
+def _file_table_module(cell: object) -> dict[str, object]:
+    return {"name": "Measurements", "type": "table", "data": [{"name": "Evidence", "type": "file", "data": [cell]}]}
+
+
+def test_item_view_file_cells_are_one_record_attachment_or_null() -> None:
+    attachment = _record_attachment()
+    for cell in (attachment, None):
+        response = ItemViewResponse.model_validate(_item_view_payload([_file_table_module(cell)]))
+        assert response.modules[0].name == "Measurements"
+
+    with pytest.raises(ValidationError):
+        _ = ItemViewResponse.model_validate(_item_view_payload([_file_table_module([attachment])]))
+
+
+def test_record_attachment_requires_all_fields_and_preserves_canonical_empty_attachment() -> None:
+    attachment = _record_attachment()
+    assert wire_models.RecordAttachment.model_validate(attachment).model_dump() == attachment
+    assert wire_models.RecordAttachment(filename="", hash="", size=0, timestamp=1).filename == ""
+
+    for field in attachment:
+        with pytest.raises(ValidationError):
+            _ = wire_models.RecordAttachment.model_validate(
+                {key: value for key, value in attachment.items() if key != field}
+            )
+    for invalid_attachment in (
+        {**attachment, "hash": "not-a-sha256"},
+        {**attachment, "size": -1},
+        {**attachment, "timestamp": 0},
+    ):
+        with pytest.raises(ValidationError):
+            _ = wire_models.RecordAttachment.model_validate(invalid_attachment)
+
+
+def test_template_json_code_modules_with_style_accept_json_string_or_null_data() -> None:
+    for data in ('{"enabled":true}', None):
+        module = wire_models.TemplateModule.model_validate(
+            {"name": "Configuration", "type": "code", "language": "json", "style": None, "data": data}
+        )
+        assert module.data == data
+
+    without_style = wire_models.TemplateModule.model_validate(
+        {"name": "Configuration", "type": "code", "language": "json", "data": {"enabled": True}}
+    )
+    assert without_style.data == {"enabled": True}
+
+    invalid_modules: tuple[dict[str, object], ...] = (
+        {"name": "Configuration", "type": "code", "language": "json", "style": None},
+        {"name": "Configuration", "type": "code", "language": "json", "style": None, "data": {}},
+    )
+    for invalid_module in invalid_modules:
+        with pytest.raises(ValidationError):
+            _ = wire_models.TemplateModule.model_validate(invalid_module)
+
+
+def test_template_number_and_boolean_cells_accept_empty_strings() -> None:
+    number = wire_models.TemplateTableColumn.model_validate(
+        {"name": "Reading", "type": "number", "data": [1, "1.5", "", None]}
+    )
+    boolean = wire_models.TemplateTableColumn.model_validate(
+        {"name": "Published", "type": "bool", "data": [True, "", None]}
+    )
+    assert number.data == [1, "1.5", "", None]
+    assert boolean.data == [True, "", None]
+
+    for invalid_column in (
+        {"name": "Reading", "type": "number", "data": ["not-a-number"]},
+        {"name": "Published", "type": "bool", "data": ["true"]},
+    ):
+        with pytest.raises(ValidationError):
+            _ = wire_models.TemplateTableColumn.model_validate(invalid_column)
+
+
+def test_save_template_content_keeps_file_cells_narrowed_to_one_attachment() -> None:
+    attachment = _record_attachment()
+    content = json.dumps([_file_table_module(attachment)])
+    request = wire_models.SaveTemplateContentRequest.model_validate({"id": 1, "data": content})
+    assert request.data == content
+
+    with pytest.raises(ValidationError):
+        _ = wire_models.SaveTemplateContentRequest.model_validate(
+            {"id": 1, "data": json.dumps([_file_table_module([attachment])])}
+        )
+
+
 def test_generated_requests_reject_unknown_fields() -> None:
     with pytest.raises(ValidationError):
         _ = ListRecordsRequest.model_validate({"eln": "Example Notebook", "unexpected": True})
@@ -364,7 +485,7 @@ def test_generated_models_cover_every_component_schema_and_non_streaming_operati
     }
     assert expected_response_models <= class_names
     assert len(operation_ids) == 71
-    assert wire_models.OPENAPI_INFO_VERSION == "0.4.2"
+    assert wire_models.OPENAPI_INFO_VERSION == "0.4.3"
 
 
 def test_generation_is_deterministic(tmp_path: Path) -> None:
@@ -476,8 +597,8 @@ def test_contract_lock_is_the_single_release_pin() -> None:
     openapi = cast(dict[str, Any], lock["openapi"])
     assert set(release) == {"tag", "commit"}
     assert set(openapi) == {"source_path", "snapshot", "sha256"}
-    assert release == {"tag": "v0.4.2", "commit": "1a4b77721d782fccd2b1f26bcc16a7d876347686"}
-    assert openapi["sha256"] == "1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b"
+    assert release == {"tag": "v0.4.3", "commit": "7965ac9803505ae35dc5ce36f52afc3c2c133c45"}
+    assert openapi["sha256"] == "6576812dd13f92ad58131f4edb8dc919d1b1fe0f19a695c2d25fbe6d13a8445b"
     assert re.fullmatch(r"[0-9a-f]{40}", cast(str, release["commit"]))
     assert re.fullmatch(r"[0-9a-f]{64}", cast(str, openapi["sha256"]))
     assert not (ROOT / "contracts" / "matelab-integration-v1.sha256").exists()

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/tests/test_record_mutations.py

@@ -342,7 +342,11 @@ async def test_record_attachment_mutations_are_separate_and_collaboration_is_not
             "type": "table",
             "rows": ["row-1"],
             "data": [
-                {"name": "Evidence", "type": "file", "data": [[{"hash": _HASH_B, "filename": "table.txt", "size": 5}]]}
+                {
+                    "name": "Evidence",
+                    "type": "file",
+                    "data": [{"hash": _HASH_B, "filename": "table.txt", "size": 5, "timestamp": 1}],
+                }
             ],
         },
         {
@@ -616,7 +620,7 @@ async def test_update_sets_one_null_table_file_cell_from_record_upload(
                 {
                     "name": "Evidence",
                     "type": "file",
-                    "data": [[{"hash": _HASH_A, "filename": "evidence.txt", "size": 5}]],
+                    "data": [{"hash": _HASH_A, "filename": "evidence.txt", "size": 5, "timestamp": 1}],
                 }
             ],
         }
@@ -676,7 +680,7 @@ async def test_update_appends_table_row_with_scalar_values_and_one_staged_file(
                 {
                     "name": "Evidence",
                     "type": "file",
-                    "data": [None, None, [{"hash": _HASH_A, "filename": "evidence.txt", "size": 5}]],
+                    "data": [None, None, {"hash": _HASH_A, "filename": "evidence.txt", "size": 5, "timestamp": 1}],
                 },
             ],
         }
@@ -774,7 +778,11 @@ async def test_update_replaces_observed_table_or_files_occurrence_with_one_inten
         "type": "table",
         "rows": ["row-1"],
         "data": [
-            {"name": "Evidence", "type": "file", "data": [[{"hash": _HASH_A, "filename": "evidence.txt", "size": 5}]]}
+            {
+                "name": "Evidence",
+                "type": "file",
+                "data": [{"hash": _HASH_A, "filename": "evidence.txt", "size": 5, "timestamp": 1}],
+            }
         ],
     }
     table_after = {
@@ -785,7 +793,7 @@ async def test_update_replaces_observed_table_or_files_occurrence_with_one_inten
             {
                 "name": "Evidence",
                 "type": "file",
-                "data": [[{"hash": _HASH_B, "filename": "replacement.txt", "size": 5}]],
+                "data": [{"hash": _HASH_B, "filename": "replacement.txt", "size": 5, "timestamp": 1}],
             }
         ],
     }
@@ -878,7 +886,7 @@ async def test_update_adds_empty_file_column_and_deletes_complete_file_fields(
                 {
                     "name": "Old evidence",
                     "type": "file",
-                    "data": [[{"hash": _HASH_B, "filename": "old.txt", "size": 5}], None],
+                    "data": [{"hash": _HASH_B, "filename": "old.txt", "size": 5, "timestamp": 1}, None],
                 },
                 {"name": "Label", "type": "text", "data": ["A", "B"]},
             ],
@@ -1035,7 +1043,7 @@ async def test_table_file_cell_prewrite_rejection_preserves_stage_for_a_later_va
                 {
                     "name": "Evidence",
                     "type": "file",
-                    "data": [[{"hash": _HASH_B, "filename": "existing.txt", "size": 5}]],
+                    "data": [{"hash": _HASH_B, "filename": "existing.txt", "size": 5, "timestamp": 1}],
                 }
             ],
         }
@@ -1057,7 +1065,7 @@ async def test_table_file_cell_prewrite_rejection_preserves_stage_for_a_later_va
                 {
                     "name": "Evidence",
                     "type": "file",
-                    "data": [[{"hash": _HASH_A, "filename": "evidence.txt", "size": 5}]],
+                    "data": [{"hash": _HASH_A, "filename": "evidence.txt", "size": 5, "timestamp": 1}],
                 }
             ],
         }

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/tests/test_records.py

@@ -145,16 +145,37 @@ async def test_read_current_record_maps_pinned_contract_success_example(
     assert record.source == source
     assert record.title == "Calibration Run"
     assert record.keywords == ("calibration",)
-    assert record.modules == (
-        {
-            "name": "Notes",
-            "type": "richtext",
-            "data": "Sanitized content",
-            "language": None,
-            "style": None,
-            "uid": "module-example",
-        },
-    )
+    assert record.modules[0] == {
+        "name": "Notes",
+        "type": "richtext",
+        "data": "Sanitized content",
+        "language": None,
+        "style": None,
+        "uid": "module-example",
+    }
+    assert record.modules[1] == {
+        "name": "Measurements",
+        "type": "table",
+        "data": [
+            {
+                "name": "Evidence",
+                "type": "file",
+                "data": [
+                    {
+                        "filename": "evidence.txt",
+                        "hash": "74034daeef860e12596c34f7e83703e668d578f4a85e72ec1645117223d4e6a7",
+                        "size": 26,
+                        "timestamp": 1_767_946_200_000,
+                    }
+                ],
+                "uid": "column-example",
+            }
+        ],
+        "language": None,
+        "style": None,
+        "uid": "table-example",
+        "rows": ["row-example"],
+    }
     assert record.versions == (RecordVersionRef(source=source, version_id=70001),)
 
 
@@ -183,7 +204,28 @@ async def test_read_current_record_maps_required_nullable_and_open_modules() ->
                             "filename": "example.bin",
                             "size": 12,
                         },
-                    }
+                    },
+                    {
+                        "type": "table",
+                        "name": "Measurements",
+                        "uid": "table-example",
+                        "rows": ["row-1", "row-2"],
+                        "data": [
+                            {
+                                "name": "Evidence",
+                                "type": "file",
+                                "data": [
+                                    {
+                                        "hash": "d6a8f491a743ee3c10b42b4519d7545d7f1d79a7e98ed2ef9c03c0c1d75a1a91",
+                                        "filename": "evidence.pdf",
+                                        "size": 34,
+                                        "timestamp": 1_767_946_200_000,
+                                    },
+                                    None,
+                                ],
+                            }
+                        ],
+                    },
                 ],
                 template_id=None,
                 datetime_modify=1_767_946_200_000,
@@ -242,14 +284,63 @@ async def test_read_current_record_maps_required_nullable_and_open_modules() ->
     assert record.author_name is None
     assert record.modules[0]["uid"] == "module-example"
     assert record.modules[0]["future_module_field"] == {"supported": True}
+    table_data = record.modules[1]["data"]
+    assert isinstance(table_data, list)
+    file_column = table_data[0]
+    assert isinstance(file_column, dict)
+    file_cells = file_column["data"]
+    assert isinstance(file_cells, list)
+    assert file_cells[1] is None
     assert record.versions[0].version_id == 70001
     assert [(item.filename, item.size, item.observed_version) for item in record.attachments] == [
-        ("example.bin", 12, None)
+        ("evidence.pdf", 34, None),
+        ("example.bin", 12, None),
     ]
     assert record.attachments[0].source == source
+    assert record.attachments[0].location is not None
+    assert record.attachments[0].location.kind == "table_file"
+    assert record.attachments[0].location.position == 0
     assert "74034dae" not in repr(record.attachments[0])
 
 
+@pytest.mark.asyncio
+async def test_read_rejects_historical_table_attachment_array_at_public_boundary() -> None:
+    payload = _item_view_payload(uid="REC-EXAMPLE-001")
+    payload["modules"] = [
+        {
+            "type": "table",
+            "name": "Measurements",
+            "rows": ["row-1"],
+            "data": [
+                {
+                    "name": "Evidence",
+                    "type": "file",
+                    "data": [
+                        [
+                            {
+                                "hash": "d6a8f491a743ee3c10b42b4519d7545d7f1d79a7e98ed2ef9c03c0c1d75a1a91",
+                                "filename": "evidence.pdf",
+                                "size": 34,
+                                "timestamp": 1_767_946_200_000,
+                            }
+                        ]
+                    ],
+                }
+            ],
+        }
+    ]
+
+    async def handler(_: Request) -> Response:
+        return Response(200, json=payload)
+
+    notebook = NotebookRef(notebook_id=23, title="Shared Example", owner_userid=202, scope="shared")
+    source = RecordLocator(notebook=notebook, record=RecordRef(record_id=9001, record_uid="REC-EXAMPLE-001"))
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=_session(), http_client=http_client)
+        with pytest.raises(MatelabProtocolError, match="does not match the Integration Contract"):
+            _ = await client.records.read(source)
+
+
 @pytest.mark.asyncio
 async def test_read_current_record_rejects_mismatched_uid() -> None:
     async def handler(_: Request) -> Response:

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a20}/uv.lock

@@ -352,7 +352,7 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.1.0a19"
+version = "0.1.0a20"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },