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

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

@@ -3,6 +3,19 @@
 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.0a21 - 2026-08-28
+
+- Adopts immutable `matelab-spec v0.4.4` at commit `be070c5f931b2063327a3beaccc53a360204b64e` and OpenAPI
+  SHA-256 `2de38e46d3814b8b049af8afd18e85fb20be6ca29cc409390d25df663abc43f9`, aligned with Provider evidence
+  `7bd9704286057653632424fa82f413d99cd69ab6`.
+- Accepts the required nullable `readRecord.datetime_locked` wire field for current unlocked records and follows the
+  unexposed `/actions/app` rename to `readApplicationBootstrap`; SDK Session identity remains sourced from token issuance.
+- Keeps `RecordFilesAttachmentAppend` root-only. The release describes a safe optional folder path in its dedicated
+  staged-name append schema, but `UpdateRecordRequest.add[]` still references `AddValueOperation`, which forbids that
+  `path`;
+  exposing it would require bypassing whole-request Contract validation. PVD-044 also records that malformed path
+  containers can silently append at root.
+
 ## 0.1.0a20 - 2026-08-24
 
 - Adopts immutable `matelab-spec v0.4.3` at commit `7965ac9803505ae35dc5ce36f52afc3c2c133c45` and OpenAPI

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a20
+Version: 0.1.0a21
 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.0a20`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a21`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
-The SDK is pinned to the immutable `matelab-spec v0.4.3` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.4.4` 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,14 +64,14 @@ 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.0a20-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a21-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
 tag, commit, and checksum recorded below.
 
 The Contract and public SDK interface track the current reviewed Provider at
-`a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27`. Provider limitations that remain relevant to integrations are documented
+`7bd9704286057653632424fa82f413d99cd69ab6`. Provider limitations that remain relevant to integrations are documented
 alongside the affected interfaces below.
 
 ## Design
@@ -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.3 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record opaque array/object
+The pinned v0.4.4 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`
@@ -316,8 +316,10 @@ supports one file column. A locally rejected target does not spend the handle; o
 result cannot be retried through the same client.
 
 Files-module append and table/files replacement use the general record attachment intents and may be combined with
-other non-conflicting record changes. `RecordFilesAttachmentAppend` targets the module root; the current Provider does
-not accept a files-folder path (PVD-044):
+other non-conflicting record changes. `RecordFilesAttachmentAppend` currently targets the module root. Although
+v0.4.4 records Provider evidence for safe folder paths, its top-level `UpdateRecordRequest.add[]` schema still excludes
+the `path` property declared by the dedicated staged-name append shape; the SDK therefore does not expose folder paths
+until that wire-schema conflict is resolved (PVD-044):
 
 ```python
 from matelab import RecordAttachmentReplacement, RecordFilesAttachmentAppend, RecordValueUpdate
@@ -427,8 +429,8 @@ and `deletePersonalLiteratureItem`.
 
 Every other implemented operation is explicitly `experimental`; the exact per-operation list and its
 PVD/PCG references live in
-`docs/operation-coverage.yaml`. `resolveCurrentIdentity` is intentionally unexposed because the SDK accepts only
-complete, integration-validated Sessions and does not bind bare external token pairs. `readLiteratureCreateTemplate`
+`docs/operation-coverage.yaml`. `readApplicationBootstrap` is intentionally unexposed because it returns the Provider
+application environment and menu model, while SDK identity is sourced from token issuance. `readLiteratureCreateTemplate`
 is intentionally unexposed because it returns a frontend form definition and an optional deployment flag rather than
 a resource needed by the SDK interface. There are no `planned` operations. Experimental support means the SDK
 validates and exposes the pinned Contract while preserving limitations such as unstable ordering/pagination,
@@ -618,8 +620,9 @@ returns the acknowledgement classification
 issue a post-write read. Database, active-browser, and unclassified acknowledgements remain distinct, and mutation
 retries stay disabled. Encrypted record content is outside the SDK's public read/update interface: the list-level
 `RecordSummary.encrypted` flag lets callers identify and skip it, while the Provider password field and frontend-only
-password lifecycle remain unexposed. Files-module attachment append is root-only because the current Provider rejects
-folder-path segments (PVD-044). A staged attachment is indeterminate once the write has started.
+password lifecycle remain unexposed. Files-module attachment append remains root-only because the pinned top-level
+update request schema does not admit the dedicated staged-name append shape's folder `path`; malformed path containers
+may also silently append at root according to PVD-044. A staged attachment is indeterminate once the write has started.
 
 Relation addition reads both endpoints and checks their resolved data server before writing; this reduces PVD-019
 risk but is not an atomic Provider authorization guarantee. It does not list relations merely to inspect the
@@ -917,6 +920,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 immutable `matelab-spec v0.4.3`, commit
-`7965ac9803505ae35dc5ce36f52afc3c2c133c45`, and OpenAPI SHA-256
-`6576812dd13f92ad58131f4edb8dc919d1b1fe0f19a695c2d25fbe6d13a8445b`.
+byte-identical wheel and source distribution hashes. The release is bound to immutable `matelab-spec v0.4.4`, commit
+`be070c5f931b2063327a3beaccc53a360204b64e`, and OpenAPI SHA-256
+`2de38e46d3814b8b049af8afd18e85fb20be6ca29cc409390d25df663abc43f9`.

{matelab_python_sdk-0.1.0a20 → matelab_python_sdk-0.1.0a21}/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.0a20`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a21`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
-The SDK is pinned to the immutable `matelab-spec v0.4.3` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.4.4` 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,14 +36,14 @@ 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.0a20-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a21-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
 tag, commit, and checksum recorded below.
 
 The Contract and public SDK interface track the current reviewed Provider at
-`a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27`. Provider limitations that remain relevant to integrations are documented
+`7bd9704286057653632424fa82f413d99cd69ab6`. Provider limitations that remain relevant to integrations are documented
 alongside the affected interfaces below.
 
 ## Design
@@ -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.3 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record opaque array/object
+The pinned v0.4.4 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`
@@ -288,8 +288,10 @@ supports one file column. A locally rejected target does not spend the handle; o
 result cannot be retried through the same client.
 
 Files-module append and table/files replacement use the general record attachment intents and may be combined with
-other non-conflicting record changes. `RecordFilesAttachmentAppend` targets the module root; the current Provider does
-not accept a files-folder path (PVD-044):
+other non-conflicting record changes. `RecordFilesAttachmentAppend` currently targets the module root. Although
+v0.4.4 records Provider evidence for safe folder paths, its top-level `UpdateRecordRequest.add[]` schema still excludes
+the `path` property declared by the dedicated staged-name append shape; the SDK therefore does not expose folder paths
+until that wire-schema conflict is resolved (PVD-044):
 
 ```python
 from matelab import RecordAttachmentReplacement, RecordFilesAttachmentAppend, RecordValueUpdate
@@ -399,8 +401,8 @@ and `deletePersonalLiteratureItem`.
 
 Every other implemented operation is explicitly `experimental`; the exact per-operation list and its
 PVD/PCG references live in
-`docs/operation-coverage.yaml`. `resolveCurrentIdentity` is intentionally unexposed because the SDK accepts only
-complete, integration-validated Sessions and does not bind bare external token pairs. `readLiteratureCreateTemplate`
+`docs/operation-coverage.yaml`. `readApplicationBootstrap` is intentionally unexposed because it returns the Provider
+application environment and menu model, while SDK identity is sourced from token issuance. `readLiteratureCreateTemplate`
 is intentionally unexposed because it returns a frontend form definition and an optional deployment flag rather than
 a resource needed by the SDK interface. There are no `planned` operations. Experimental support means the SDK
 validates and exposes the pinned Contract while preserving limitations such as unstable ordering/pagination,
@@ -590,8 +592,9 @@ returns the acknowledgement classification
 issue a post-write read. Database, active-browser, and unclassified acknowledgements remain distinct, and mutation
 retries stay disabled. Encrypted record content is outside the SDK's public read/update interface: the list-level
 `RecordSummary.encrypted` flag lets callers identify and skip it, while the Provider password field and frontend-only
-password lifecycle remain unexposed. Files-module attachment append is root-only because the current Provider rejects
-folder-path segments (PVD-044). A staged attachment is indeterminate once the write has started.
+password lifecycle remain unexposed. Files-module attachment append remains root-only because the pinned top-level
+update request schema does not admit the dedicated staged-name append shape's folder `path`; malformed path containers
+may also silently append at root according to PVD-044. A staged attachment is indeterminate once the write has started.
 
 Relation addition reads both endpoints and checks their resolved data server before writing; this reduces PVD-019
 risk but is not an atomic Provider authorization guarantee. It does not list relations merely to inspect the
@@ -889,6 +892,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 immutable `matelab-spec v0.4.3`, commit
-`7965ac9803505ae35dc5ce36f52afc3c2c133c45`, and OpenAPI SHA-256
-`6576812dd13f92ad58131f4edb8dc919d1b1fe0f19a695c2d25fbe6d13a8445b`.
+byte-identical wheel and source distribution hashes. The release is bound to immutable `matelab-spec v0.4.4`, commit
+`be070c5f931b2063327a3beaccc53a360204b64e`, and OpenAPI SHA-256
+`2de38e46d3814b8b049af8afd18e85fb20be6ca29cc409390d25df663abc43f9`.

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

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

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

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Matelab Integration Contract
-  version: 0.4.3
+  version: 0.4.4
   description: |
     Current PHP wire contract for generating SDKs against the selected
     `matelab-server` Provider version.
@@ -9,7 +9,7 @@ info:
   x-contract-line: integration-v1
   x-provider-evidence:
     repository: /home/tnzhu/projects/matelab-server
-    commit: a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27
+    commit: 7bd9704286057653632424fa82f413d99cd69ab6
     files:
       - controller/Actions.php
       - controller/Tokens.php
@@ -39,8 +39,8 @@ info:
       - sql/matelab.sql
       - sql/recommend.sql
   x-provider-audit:
-    currentCommit: a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27
-    previousReleaseEvidenceCommit: 59101f006e9fd6d6ce0b951dfd34695a7949b54f
+    currentCommit: 7bd9704286057653632424fa82f413d99cd69ab6
+    previousReleaseEvidenceCommit: a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27
     contractStatus: current-provider-aligned
     incorporatedChanges:
       - {operationId: stageTemporaryFile, change: staging-identifiers-expanded-to-100}
@@ -49,8 +49,10 @@ info:
       - {operationId: importRecordDataset, change: explicit-null-table-file-cells-rejected}
       - {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: updateRecordData, change: safe-files-folder-path-restored-to-callable-shape}
+      - {operationId: readApplicationBootstrap, change: identity-and-notifications-moved-out-of-app-response}
       - {operationId: readRecord, change: table-file-cell-readback-modeled-as-attachment-object-or-null}
+      - {operationId: readRecord, change: current-unlocked-datetime-locked-may-be-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}
@@ -68,8 +70,11 @@ info:
         record and currently resolves its private staging state through a
         native `#hash` reference.
 
-        The MCP identity, ELN-group list, and notebook-list calls currently use
-        non-contract POST and must migrate to GET.
+        At this recorded MCP commit, identity resolution used a non-contract
+        POST to `/actions/app`. The current Provider removed identity from that
+        response, so this historical call cannot define current wire; session
+        identity must come from token issuance. ELN-group and notebook-list
+        calls still provide Consumer evidence for their canonical GET forms.
     - repository: /home/tnzhu/projects/matelab-front
       commit: 3c356731e883f6035fc4b475b84982739bba4095
       files:
@@ -85,6 +90,11 @@ info:
         - src/views/recommend/fav.vue
         - src/views/recommend/favDetail.vue
         - src/views/recommend/favItems.vue
+      note: |
+        This Front commit reads environment/menu and identity/notifications
+        from `/actions/app`. The current Provider moved the latter fields out
+        of that route; only the still-callable application-bootstrap use case
+        defines the current `/actions/app` contract.
   x-record-attachment-staging:
     status: contract-contained
     producerOperationId: uploadRecordAttachment
@@ -132,8 +142,8 @@ info:
           operationArrays: [add]
           attachmentOperationSchema:
             $ref: "#/components/schemas/AppendFilesModuleStagedAttachmentOperation"
-          folderPath: omitted
-          readback: one-new-canonical-files-entry
+          folderPath: optional-non-empty-safe-segments
+          readback: one-new-canonical-files-entry-at-root-or-resolved-folder
         tableFileCellReplacement:
           operationArrays: [modify]
           attachmentOperationSchema:
@@ -227,15 +237,15 @@ tags:
 paths:
   /actions/app:
     get:
-      operationId: resolveCurrentIdentity
+      operationId: readApplicationBootstrap
       tags: [Authentication]
-      summary: Resolve the authenticated Matelab identity and application environment
+      summary: Read the authenticated Matelab application bootstrap
       description: |
-        Read-only application bootstrap used by Matelab Front and the only
-        `/actions/app` method in integration-v1. The MCP
-        consumer uses `user.userid`, `user.username`, and required-nullable
-        `user.email`; the remaining fields drive the Provider UI and are retained
-        because they are part of the PHP wire response.
+        Read-only environment, product-name, AI and menu bootstrap used by
+        Matelab Front and the only `/actions/app` method in integration-v1.
+        The current Provider no longer returns `user` or `notifications` from
+        this route; authenticated identity is available from token issuance
+        flows and is not inferred from this response.
       security:
         - bearerAuth: []
       responses:
@@ -245,22 +255,16 @@ paths:
             application/json:
               schema:
                 oneOf:
-                  - $ref: "#/components/schemas/AppIdentityResponse"
+                  - $ref: "#/components/schemas/AppBootstrapResponse"
                   - $ref: "#/components/schemas/ErrorResponse"
               examples:
                 success:
-                  summary: Authenticated identity with no unread notifications
+                  summary: Application bootstrap with enabled ELN navigation
                   value:
                     code: 0
                     msg: ""
                     errcode: 0
                     errmsg: ""
-                    user:
-                      username: Example User
-                      avatar: null
-                      email: user@example.invalid
-                      userid: 101
-                    notifications: []
                     env:
                       ai: false
                       smtp: true
@@ -292,22 +296,12 @@ paths:
                             url: /db/eln
                             order: 1
                 nullable:
-                  summary: Identity fields backed by nullable user columns
+                  summary: Application bootstrap with no licensed institute features
                   value:
                     code: 0
                     msg: ""
                     errcode: 0
                     errmsg: ""
-                    user:
-                      username: null
-                      avatar: null
-                      email: null
-                      userid: 102
-                    notifications:
-                      - id: 501
-                        showtext: null
-                        datetime_add: "2026-01-02 08:00:00"
-                        datetime: "2026-01-02 08:00"
                     env:
                       ai: false
                       smtp: false
@@ -1693,8 +1687,10 @@ paths:
         or replacing an exact table file cell, appending a table row and
         setting its file cell in the same request, appending one root files
         entry, and replacing one files entry by an immediately read index.
-        Files-module folder `path` is not part of the callable request shape
-        because the current Provider rejects valid path segments under PVD-044.
+        Files-module folder `path` accepts a non-empty list of safe folder-name
+        segments. PVD-044 remains because malformed or empty path containers are
+        not reliably rejected by the Provider; those shapes stay outside the
+        callable request schema.
         Form-file replacement remains unsafe under PVD-014. Richtext only
         recognizes hash-bearing `elnurl://` references; `#file{name}` is plain
         text there, while the hash path can fall back to an existing quote and
@@ -2572,7 +2568,7 @@ paths:
                     uid: REC-EXAMPLE-001
                     current_version: 70001
                     item_id: 9001
-                    datetime_locked: 0
+                    datetime_locked: null
                     locked: false
                     signs: []
                     signed: false
@@ -4468,13 +4464,11 @@ components:
             filename: {type: string, minLength: 1}
             size: {type: integer, minimum: 0}
             hash: {$ref: "#/components/schemas/Sha256"}
-    AppIdentityResponse:
+    AppBootstrapResponse:
       allOf:
         - $ref: "#/components/schemas/ResponseEnvelope"
         - type: object
           required:
-            - user
-            - notifications
             - env
             - ai_enable
             - ai_text
@@ -4488,13 +4482,6 @@ components:
               const: 0
             errcode:
               const: 0
-            user:
-              $ref: "#/components/schemas/AppUser"
-            notifications:
-              type: array
-              maxItems: 5
-              items:
-                $ref: "#/components/schemas/AppNotification"
             env:
               $ref: "#/components/schemas/AppEnvironment"
             ai_enable:
@@ -4516,36 +4503,6 @@ components:
               type: array
               items:
                 $ref: "#/components/schemas/AppMenu"
-    AppUser:
-      type: object
-      required: [username, avatar, email, userid]
-      properties:
-        username:
-          type: [string, "null"]
-          description: Raw nullable `login_user.realname`.
-        avatar:
-          type: [string, "null"]
-          description: Raw id-photo path, normalized to null when empty.
-        email:
-          type: [string, "null"]
-        userid:
-          type: integer
-          minimum: 1
-    AppNotification:
-      type: object
-      required: [id, showtext, datetime_add, datetime]
-      properties:
-        id:
-          type: integer
-          minimum: 1
-        showtext:
-          type: [string, "null"]
-        datetime_add:
-          type: [string, "null"]
-          description: Raw database datetime retained by the PHP response.
-        datetime:
-          type: string
-          description: Provider-formatted `Y-m-d H:i`.
     AppEnvironment:
       type: object
       required:
@@ -5642,6 +5599,17 @@ components:
       required: [module, data]
       properties:
         module: {type: string, minLength: 1}
+        path:
+          type: array
+          minItems: 1
+          items:
+            type: string
+            minLength: 1
+            maxLength: 245
+            pattern: '^[^/:*?"<>\\|]+$'
+          description: |
+            Ordered folder names below the files-module root. Existing folders
+            are reused by exact name and parent; missing folders are created.
         data:
           type: object
           required: [file, text]
@@ -5651,8 +5619,10 @@ components:
           additionalProperties: false
       additionalProperties: false
       description: |
-        Appends one staged attachment to the root of an existing files module.
-        Folder `path` is intentionally outside the verified shape.
+        Appends one staged attachment to the root of an existing files module
+        when `path` is absent, or below the resolved folder path when present.
+        Empty and malformed path containers are intentionally outside the
+        callable shape because the Provider treats some of them as root append.
     ReplaceFilesModuleStagedAttachmentOperation:
       type: object
       required: [path, data]
@@ -6557,9 +6527,12 @@ components:
               type: integer
               minimum: 1
             datetime_locked:
-              type: integer
+              type: [integer, "null"]
               minimum: 0
-              description: Unix timestamp in milliseconds, or zero.
+              description: |
+                Unix timestamp in milliseconds; null for the current unlocked
+                record. Provider paths that normalize the absent timestamp may
+                return zero.
             locked:
               type: boolean
             signs:

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

@@ -3,11 +3,11 @@
 schema_version: 1
 contract:
   line: integration-v1
-  release: v0.4.3
+  release: v0.4.4
   operation_count: 71
 
 operations:
-  - operation_id: resolveCurrentIdentity
+  - operation_id: readApplicationBootstrap
     method: GET
     path: /actions/app
     domain: authentication
@@ -15,8 +15,8 @@ operations:
     stability: not_applicable
     public_interface: null
     known_issues: []
-    limitation: The SDK accepts only complete, integration-validated Sessions and does not bind bare external tokens.
-    reopen_when: A Provider-independent SDK use case requires explicit identity re-resolution for an existing Session.
+    limitation: The Provider response is an application bootstrap model; SDK identity remains sourced from token issuance.
+    reopen_when: A Provider-independent SDK use case requires the Provider application environment or menu model.
 
   - operation_id: loginTokenSet
     method: POST

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

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

{matelab_python_sdk-0.1.0a20 → matelab_python_sdk-0.1.0a21}/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.3"
+OPENAPI_INFO_VERSION = "0.4.4"
 
 
 class ResponseEnvelope(WireModel):
@@ -380,32 +380,6 @@ class UploadAttachmentResponse(WireModel):
     hash: Sha256
 
 
-class AppUser(WireModel):
-    username: Annotated[str | None, Field(...)]
-    """
-    Raw nullable `login_user.realname`.
-    """
-    avatar: Annotated[str | None, Field(...)]
-    """
-    Raw id-photo path, normalized to null when empty.
-    """
-    email: Annotated[str | None, Field(...)]
-    userid: Annotated[StrictInt, Field(ge=1)]
-
-
-class AppNotification(WireModel):
-    id: Annotated[StrictInt, Field(ge=1)]
-    showtext: Annotated[str | None, Field(...)]
-    datetime_add: Annotated[str | None, Field(...)]
-    """
-    Raw database datetime retained by the PHP response.
-    """
-    datetime: str
-    """
-    Provider-formatted `Y-m-d H:i`.
-    """
-
-
 class AppEnvironment(WireModel):
     ai: StrictBool
     smtp: StrictBool
@@ -1572,6 +1546,10 @@ class AppendTableRowOperation(WireModel):
     row: Annotated[StrictInt, Field(ge=-1, le=-1)]
 
 
+class PathItem3(RootModel[str]):
+    root: Annotated[str, Field(max_length=245, min_length=1, pattern='^[^/:*?"<>\\\\|]+$')]
+
+
 class Data(WireModel):
     model_config = ConfigDict(extra="forbid")
     file: StagedRecordAttachmentReference
@@ -1581,20 +1559,26 @@ class Data(WireModel):
 class AppendFilesModuleStagedAttachmentOperation(WireModel):
     model_config = ConfigDict(extra="forbid")
     module: Annotated[str, Field(min_length=1)]
+    path: Annotated[list[PathItem3] | None, Field(min_length=1)] = None
+    """
+    Ordered folder names below the files-module root. Existing folders
+    are reused by exact name and parent; missing folders are created.
+
+    """
     data: Data
 
 
-class PathItem3(RootModel[str]):
+class PathItem4(RootModel[str]):
     root: Annotated[str, Field(min_length=1)]
 
 
-class PathItem4(RootModel[StrictInt]):
+class PathItem5(RootModel[StrictInt]):
     root: Annotated[StrictInt, Field(ge=0)]
 
 
 class ReplaceFilesModuleStagedAttachmentOperation(WireModel):
     model_config = ConfigDict(extra="forbid")
-    path: tuple[PathItem3, PathItem4]
+    path: tuple[PathItem4, PathItem5]
     data: Data
 
 
@@ -1605,18 +1589,18 @@ class AddEmptyFileTableColumnOperation(WireModel):
     type: Literal["file"]
 
 
-class PathItem5(RootModel[str]):
+class PathItem6(RootModel[str]):
     root: Annotated[str, Field(min_length=1)]
 
 
 class DeleteWholeFileFormFieldOperation(WireModel):
     model_config = ConfigDict(extra="forbid")
-    path: tuple[PathItem5, PathItem5]
+    path: tuple[PathItem6, PathItem6]
 
 
 class DeleteWholeFileTableColumnOperation(WireModel):
     model_config = ConfigDict(extra="forbid")
-    path: tuple[PathItem5, PathItem5]
+    path: tuple[PathItem6, PathItem6]
 
 
 class User2(RootModel[StrictInt]):
@@ -3757,9 +3741,12 @@ class ItemViewResponse(WireModel):
     """
     current_version: Annotated[StrictInt, Field(ge=0)]
     item_id: Annotated[StrictInt, Field(ge=1)]
-    datetime_locked: Annotated[StrictInt, Field(ge=0)]
+    datetime_locked: Annotated[StrictInt | None, Field(ge=0)]
     """
-    Unix timestamp in milliseconds, or zero.
+    Unix timestamp in milliseconds; null for the current unlocked
+    record. Provider paths that normalize the absent timestamp may
+    return zero.
+
     """
     locked: StrictBool
     signs: list[RecordSignature]
@@ -3991,7 +3978,7 @@ class ListCloudDriveFilesResponse(RootModel[CloudDriveFileListResponse | ErrorRe
     root: CloudDriveFileListResponse | ErrorResponse
 
 
-class AppIdentityResponse(WireModel):
+class AppBootstrapResponse(WireModel):
     code: Annotated[StrictInt, Field(ge=0, le=0)]
     msg: str
     """
@@ -4011,8 +3998,6 @@ class AppIdentityResponse(WireModel):
     diagnostic field.
 
     """
-    user: AppUser
-    notifications: Annotated[list[AppNotification], Field(max_length=5)]
     env: AppEnvironment
     ai_enable: StrictBool
     ai_text: Annotated[list[str], Field(min_length=1)]
@@ -4102,8 +4087,8 @@ class LiteratureContent(RootModel[LiteratureContentObject | LiteratureContent1])
     root: LiteratureContentObject | LiteratureContent1
 
 
-class ResolveCurrentIdentityResponse(RootModel[AppIdentityResponse | ErrorResponse]):
-    root: AppIdentityResponse | ErrorResponse
+class ReadApplicationBootstrapResponse(RootModel[AppBootstrapResponse | ErrorResponse]):
+    root: AppBootstrapResponse | ErrorResponse
 
 
 class ListNotebooksResponse(RootModel[NotebookListResponse | ErrorResponse]):

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

@@ -88,7 +88,7 @@ def test_generated_response_preserves_required_nullable_fields() -> None:
             "uid": None,
             "current_version": 0,
             "item_id": 1,
-            "datetime_locked": 0,
+            "datetime_locked": None,
             "locked": False,
             "signs": [],
             "signed": False,
@@ -106,6 +106,8 @@ def test_generated_response_preserves_required_nullable_fields() -> None:
     )
     assert ItemViewResponse.model_fields["keywords"].is_required()
     assert response.keywords is None
+    assert ItemViewResponse.model_fields["datetime_locked"].is_required()
+    assert response.datetime_locked is None
 
 
 def _item_view_payload(modules: list[object]) -> dict[str, object]:
@@ -435,6 +437,10 @@ def test_generated_v012_attachment_write_shapes_are_strict_and_dedicated() -> No
             "AppendFilesModuleStagedAttachmentOperation",
             {"module": "Files", "data": {"file": staged, "text": "Evidence"}},
         ),
+        (
+            "AppendFilesModuleStagedAttachmentOperation",
+            {"module": "Files", "path": ["Evidence", "Raw Data"], "data": {"file": staged, "text": "Evidence"}},
+        ),
         (
             "ReplaceFilesModuleStagedAttachmentOperation",
             {"path": ["Files", 0], "data": {"file": staged, "text": "Replacement"}},
@@ -445,7 +451,7 @@ def test_generated_v012_attachment_write_shapes_are_strict_and_dedicated() -> No
     )
     for model_name, payload in valid_shapes:
         model = cast(type[BaseModel], getattr(wire_models, model_name))
-        assert model.model_validate(payload).model_dump(mode="json") == payload
+        assert model.model_validate(payload).model_dump(mode="json", exclude_none=True) == payload
 
     invalid_shapes: tuple[tuple[str, dict[str, object]], ...] = (
         ("SetTableFileCellWithStagedAttachmentOperation", {"path": ["Measurements", "Evidence"], "data": staged}),
@@ -454,6 +460,26 @@ def test_generated_v012_attachment_write_shapes_are_strict_and_dedicated() -> No
             "AppendFilesModuleStagedAttachmentOperation",
             {"module": "Files", "data": {"file": "#hash{file, hash}", "text": "Evidence"}},
         ),
+        (
+            "AppendFilesModuleStagedAttachmentOperation",
+            {"module": "Files", "path": [], "data": {"file": staged, "text": "Evidence"}},
+        ),
+        (
+            "AppendFilesModuleStagedAttachmentOperation",
+            {"module": "Files", "path": ["Folder/Child"], "data": {"file": staged, "text": "Evidence"}},
+        ),
+        (
+            "AppendFilesModuleStagedAttachmentOperation",
+            {"module": "Files", "path": [""], "data": {"file": staged, "text": "Evidence"}},
+        ),
+        (
+            "AppendFilesModuleStagedAttachmentOperation",
+            {"module": "Files", "path": ["x" * 246], "data": {"file": staged, "text": "Evidence"}},
+        ),
+        (
+            "AppendFilesModuleStagedAttachmentOperation",
+            {"module": "Files", "path": [1], "data": {"file": staged, "text": "Evidence"}},
+        ),
         (
             "AddEmptyFileTableColumnOperation",
             {"module": "Measurements", "name": "Evidence", "type": "file", "data": []},
@@ -466,6 +492,18 @@ def test_generated_v012_attachment_write_shapes_are_strict_and_dedicated() -> No
             _ = model.model_validate(payload)
 
 
+def test_update_record_request_still_excludes_dedicated_files_folder_path() -> None:
+    operation = {
+        "module": "Files",
+        "path": ["Evidence", "Raw Data"],
+        "data": {"file": "#file{staged-example}", "text": "Evidence"},
+    }
+    _ = wire_models.AppendFilesModuleStagedAttachmentOperation.model_validate(operation)
+
+    with pytest.raises(ValidationError):
+        _ = wire_models.UpdateRecordRequest.model_validate({"eln": "Example", "uid": "REC-001", "add": [operation]})
+
+
 def test_generated_models_cover_every_component_schema_and_non_streaming_operation() -> None:
     document = _load_openapi()
     components = cast(dict[str, Any], document["components"])
@@ -485,7 +523,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.3"
+    assert wire_models.OPENAPI_INFO_VERSION == "0.4.4"
 
 
 def test_generation_is_deterministic(tmp_path: Path) -> None:
@@ -597,8 +635,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.3", "commit": "7965ac9803505ae35dc5ce36f52afc3c2c133c45"}
-    assert openapi["sha256"] == "6576812dd13f92ad58131f4edb8dc919d1b1fe0f19a695c2d25fbe6d13a8445b"
+    assert release == {"tag": "v0.4.4", "commit": "be070c5f931b2063327a3beaccc53a360204b64e"}
+    assert openapi["sha256"] == "2de38e46d3814b8b049af8afd18e85fb20be6ca29cc409390d25df663abc43f9"
     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.0a20 → matelab_python_sdk-0.1.0a21}/tests/test_operation_coverage.py

@@ -149,5 +149,5 @@ def test_completed_coverage_has_only_intentionally_unexposed_operations() -> Non
 
     assert non_implemented == {
         "readLiteratureCreateTemplate": "intentionally_unexposed",
-        "resolveCurrentIdentity": "intentionally_unexposed",
+        "readApplicationBootstrap": "intentionally_unexposed",
     }

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

@@ -243,7 +243,7 @@ async def test_read_current_record_maps_required_nullable_and_open_modules() ->
                 uid="REC-EXAMPLE-001",
                 current_version=70001,
                 item_id=9001,
-                datetime_locked=0,
+                datetime_locked=None,
                 locked=False,
                 signs=[
                     {

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

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