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

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

@@ -3,6 +3,31 @@
 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
+  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.0a21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a19
+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.0a19`. `[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 rewritten `matelab-spec v0.4.2` 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.0a19-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.2 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
@@ -348,7 +350,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
@@ -425,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,
@@ -500,9 +504,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
@@ -613,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
@@ -912,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 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.4`, commit
+`be070c5f931b2063327a3beaccc53a360204b64e`, and OpenAPI SHA-256
+`2de38e46d3814b8b049af8afd18e85fb20be6ca29cc409390d25df663abc43f9`.

{matelab_python_sdk-0.1.0a19 → 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.0a19`. `[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 rewritten `matelab-spec v0.4.2` 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.0a19-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.2 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
@@ -320,7 +322,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
@@ -397,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,
@@ -472,9 +476,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
@@ -585,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
@@ -884,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 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.4`, commit
+`be070c5f931b2063327a3beaccc53a360204b64e`, and OpenAPI SHA-256
+`2de38e46d3814b8b049af8afd18e85fb20be6ca29cc409390d25df663abc43f9`.

{matelab_python_sdk-0.1.0a19 → 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.2",
-    "commit": "1a4b77721d782fccd2b1f26bcc16a7d876347686"
+    "tag": "v0.4.4",
+    "commit": "be070c5f931b2063327a3beaccc53a360204b64e"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b"
+    "sha256": "2de38e46d3814b8b049af8afd18e85fb20be6ca29cc409390d25df663abc43f9"
   }
 }

{matelab_python_sdk-0.1.0a19 → 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.2
+  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,7 +49,13 @@ 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}
   x-consumer-evidence:
     - repository: /home/tnzhu/projects/matelab-mcp
       commit: 94a129b2df0ef0fbcf179c10550fb7c9a5dd2e6f
@@ -64,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:
@@ -81,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
@@ -128,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:
@@ -223,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:
@@ -241,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
@@ -288,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
@@ -827,6 +825,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
@@ -1688,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
@@ -2541,6 +2542,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
@@ -2554,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
@@ -4450,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
@@ -4470,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:
@@ -4498,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:
@@ -4914,7 +4889,7 @@ components:
             required: [data]
             properties:
               data:
-                type: string
+                type: [string, "null"]
                 contentMediaType: application/json
       additionalProperties: true
     TemplateTableColumn:
@@ -4949,6 +4924,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 +4933,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 +4947,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]
@@ -5603,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]
@@ -5612,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]
@@ -6518,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: