matelab-python-sdk 0.1.0a22__tar.gz → 0.1.0a24__tar.gz

{matelab_python_sdk-0.1.0a22 → matelab_python_sdk-0.1.0a24}/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.0a24 - 2026-09-26
+
+- Adopts immutable `matelab-spec v0.5.0` at commit `4f2959472933da47d1ea3e275552884d51d4fdd9`
+  (annotated tag object `cc362a9a36601f5d07d6e90c2c6994e33c202d88`) and OpenAPI SHA-256
+  `dee14f76e24b2d7c3d97a6f30a9369ac093d615d132db85836ab86671eadcf18`, aligned with Provider source evidence
+  `acb0e12f2d62a8959ab9e9bddf38e34a67c19b48`. The release evidence covers an isolated Provider, not production.
+- Breaking: `templates.save_content()` rejects invalid JSON in JSON code modules with non-null `style` before HTTP.
+  Generated write models and whole-request validation now enforce nested JSON content schemas. Readback continues to
+  preserve raw code strings (including empty or non-JSON text) and null; reading a module does not guarantee it can
+  be saved unchanged. JSON code without a style, or with null style, retains its existing write boundary.
+- Regenerates the private application bootstrap fields and credential-login restriction to an omitted or empty
+  WeChat code. Public credential login already omits that input. Record module creation preserves explicit code
+  strings and leaves omitted/null initialization to the Provider, which now uses an empty string without synthesizing
+  an ECharts series object.
+- Documents Chat SSO expiry against the user's mutable activity timestamp, single-attempt exchange, and lack of
+  concurrent one-time guarantees. Synchronizes the release's PVD/PCG renumbering and retired comment-upload issue.
+- Keeps staged files-module append root-only because its dedicated schema and `UpdateRecordRequest.add[]` still
+  disagree about folder paths (now PVD-030). Retains the read-only missing table-attachment timestamp compatibility.
+
+## 0.1.0a23 - 2026-09-04
+
+- Temporarily accepts `readRecord` table file attachments that contain valid `filename`, `hash`, and `size` fields but
+  omit the Contract-required `timestamp`. The SDK preserves the omission instead of synthesizing a timestamp; explicit
+  null timestamps and other malformed attachment values remain rejected.
+
 ## 0.1.0a22 - 2026-09-03
 
 - Adopts immutable `matelab-spec v0.4.5` at commit `6afac7ff151680130e6e4bc6d95782589b97f4e7` and OpenAPI

{matelab_python_sdk-0.1.0a22 → matelab_python_sdk-0.1.0a24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a22
+Version: 0.1.0a24
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -35,12 +35,14 @@ 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.0a22`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a24`. `[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.5` 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.
+The SDK is pinned to the immutable `matelab-spec v0.5.0` Contract Release. The sole pin,
+`contracts/matelab-integration-v1.lock.json`, records peeled commit `4f2959472933da47d1ea3e275552884d51d4fdd9`,
+source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path, and SHA-256
+`dee14f76e24b2d7c3d97a6f30a9369ac093d615d132db85836ab86671eadcf18`. The annotated tag object is
+`cc362a9a36601f5d07d6e90c2c6994e33c202d88`.
 
 ## Installation
 
@@ -64,15 +66,17 @@ 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.0a22-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a24-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
-`59eb05b233e5ddd023a60ccb5e5c5f2ae22a70f0`. Provider limitations that remain relevant to integrations are documented
-alongside the affected interfaces below.
+The Contract uses Provider source evidence from `acb0e12f2d62a8959ab9e9bddf38e34a67c19b48`; v0.5.0 validation ran
+against an isolated test instance and does not establish production behavior. The corresponding Front Consumer evidence
+is `0c985f5b6da8e8ef4627ca7065cea85e408ae981`; it informs cross-Consumer capability review but does not define the SDK
+interface. Provider limitations that remain relevant to integrations are documented alongside the affected interfaces
+below.
 
 ## Design
 
@@ -121,7 +125,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.5 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record opaque array/object
+The pinned v0.5.0 Contract also declares optional code-4 `errs`, but PVD-029 and PCG-010 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`
@@ -317,9 +321,9 @@ 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` currently targets the module root. Although
-v0.4.5 records Provider evidence for safe folder paths, its top-level `UpdateRecordRequest.add[]` schema still excludes
+v0.5.0 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):
+until that wire-schema conflict is resolved (PVD-030):
 
 ```python
 from matelab import RecordAttachmentReplacement, RecordFilesAttachmentAppend, RecordValueUpdate
@@ -333,6 +337,11 @@ await client.records.update(
 )
 ```
 
+For `RecordModuleCreation(module_type="code", language="json", style="echarts")`, omitted, null, and empty `data` all
+produce an empty string; explicit `"0"` stays `"0"`. Send the desired initial chart configuration as a JSON code string.
+Richtext/code module creation defaults missing `data` to `""`; form/table/files creation ignores it and initializes
+content as `[]`.
+
 A replacement starts with an occurrence returned by `records.read()`; applications must not fabricate a
 `RecordAttachmentRef`. The same `RecordAttachmentReplacement` covers both table-file and files-module occurrences:
 
@@ -354,6 +363,12 @@ not accept a caption. Record reads likewise accept only one canonical attachment
 an attachment array violates the pinned response contract. Both replacement forms require the replacement hash to
 differ from the current occurrence.
 
+As a temporary Provider-compatibility exception, `records.read()` also accepts a table file attachment object whose
+otherwise valid `filename`, `hash`, and `size` are present but whose Contract-required `timestamp` is omitted. The SDK
+preserves that omission in `Record.modules` and does not invent a timestamp; null timestamps and all other malformed
+attachment shapes remain response errors. This exception can be removed after the Provider canonicalizes current and
+historical record content.
+
 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
 must not be called while a concurrent editor is known to be active. The Provider offers no expected hash or revision,
@@ -430,7 +445,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`. `readApplicationBootstrap` is intentionally unexposed because it returns the Provider
-application environment and menu model, while SDK identity is sourced from token issuance. `readLiteratureCreateTemplate`
+application environment and menu model, including required `data_express_enable` and `data_express_text` fields, 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,
@@ -444,6 +460,13 @@ automatically retried, and the returned token set is stored in the same in-memor
 session = await client.exchange_chat_sso_code(code="chat-sanitizedcode123", key="sanitized-shared-key")
 ```
 
+The code suffix must be non-empty and the shared key must be non-blank. The Provider rejects a code after the current
+user's `active_datetime` plus 300 seconds; that timestamp can change through other user activity, so Consumers must not
+derive a deadline from the code or automatically retry an uncertain exchange. A sequential replay is rejected, but the
+Provider's read-then-clear implementation does not guarantee that concurrent exchanges have only one winner.
+Ordinary credential login does not expose the non-empty WeChat binding code branch, which can reassign another account's
+OpenID (PVD-032).
+
 Group and user discovery expose sharing identities without inventing Provider pagination:
 
 ```python
@@ -454,7 +477,7 @@ targets = await client.users.search("Example Researcher", global_scope=False)
 `groups.list()` returns the `GroupSummary` tuple directly. Ordering remains Provider-unspecified and is documented
 rather than repeated as a constant result field. The Provider's members for an unstable first group remain wire-only;
 `users.search()` is the public recipient-discovery interface. These two discovery interfaces are experimental because
-group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-006, PVD-029).
+group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-017, PVD-025).
 `GroupSummary.notebook_creation_available` expresses whether the group can currently host notebook creation without
 exposing the Provider's data-server routing value.
 
@@ -479,7 +502,7 @@ Consequently, update performs one list pre-read followed by the write. This pres
 Provider offers no compare-and-swap or atomic read-modify-write operation. Call `list()` or `shares()` explicitly when
 the application needs current state. `NotebookPermissions` normalizes the Provider's stored and effective masks and
 is reused by record pages instead of maintaining a second nearly identical permission model. Direct shares always
-have implicit read access even when every optional permission is false (PVD-010).
+have implicit read access even when every optional permission is false (PVD-037).
 `provider_signing_allowed` only represents Provider policy, not an SDK signing operation. Share-list order remains
 unspecified.
 
@@ -504,17 +527,19 @@ 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. 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
+types. A JSON-language code module's `data` remains code text and may be empty, null, or invalid JSON;
+`language=json` does not imply that Consumers can parse it. When template content contains a code module with
+`language=json` and non-null `style`, its code text must be valid JSON to save. 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),
+must remain a canonical module list, and a table file cell must be one canonical attachment object or `null` (PVD-013).
+The Provider supports only whole-content replacement and has no atomic patch or compare-and-swap operation (PCG-008),
 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
 because Provider discovery ordering/pagination and historical `images` compatibility are not fully stable
-(PCG-003, PCG-009, PVD-013, PVD-022).
+(PCG-011, PCG-012, PVD-038, PVD-022).
 
 `templates.list()` returns one tuple. `TemplateSummary.scope` is limited to `owned`, `shared`, `group`, and `public`;
 Provider marketplace acquisitions and system defaults are both public templates. An acquired public template carries
@@ -529,7 +554,7 @@ transaction. Creation returns the new `TemplateRef`; metadata replacement and ot
 the Provider supplies no new resource representation. `update()` therefore requires the complete title, summary, and
 keyword set rather than implying a partial patch. `update_usage()` generates the Provider's required fresh hidden
 correlation value internally. Usage attachments remain unsupported until their staging and binding lifecycle is
-contracted safely (PVD-026). Marketplace revision limitations remain explicit through `content_version`,
+contracted safely (PVD-003). Marketplace revision limitations remain explicit through `content_version`,
 `published_content_version`, and `market_review_reason` (PVD-021).
 
 Extended record reads stay behind the same `records` interface:
@@ -549,7 +574,7 @@ relations = await client.records.relations(source)
 as `modules`; it is not the template-shaped `RecordImportItem.data` accepted by record import.
 `records.search()` maps each requested field name to a stored record path. A match exposes only Provider-returned
 entries in `values`, so key membership distinguishes an absent result from an explicit JSON `null`.
-The current Provider excludes encrypted records from search (PVD-043); an empty search result therefore does
+The current Provider excludes encrypted records from search (PVD-041); an empty search result therefore does
 not prove that no matching encrypted record exists.
 
 The Provider calls its notebook directory tree `subtype`; that name remains wire-only. The SDK exposes
@@ -559,7 +584,7 @@ The Provider calls its notebook directory tree `subtype`; that name remains wire
 positive folder ID for one folder.
 
 `records.page` fixes the legacy request to `page_size=0&default=1`, preventing the known owner-preference writes
-described by PVD-039; its total is derived internally from the Provider's complete matching ID list. The result keeps
+described by PVD-028; its total is derived internally from the Provider's complete matching ID list. The result keeps
 semantic `NotebookPermissions` directly, without a shallow context model or duplicated notebook/owner/template
 display metadata. Effective request pagination, the UI selection list and Provider keyword-filter echo are not exposed.
 Its `search` argument, shared with `records.list()`, maps the Provider's wire-level `content` filter without exposing
@@ -597,10 +622,10 @@ imported = await client.records.import_dataset(
 
 Blank-record creation returns `None` because the Provider returns no record identity, even when the caller supplies a
 UID. Import validates the complete batch with generated wire models but cannot map returned database IDs to
-individual inputs or promise atomicity (PCG-008); it therefore returns only the tuple of database IDs actually
+individual inputs or promise atomicity (PCG-009); it therefore returns only the tuple of database IDs actually
 reported by the Provider. `RecordImportItem.keywords` is a tuple; the adapter owns the Provider's
 legacy semicolon encoding. Folder paths are ordered existing folder titles from the notebook root; they do not create
-missing folders. The current Provider rejects explicit-null table-file imports (PVD-045). Because the SDK accepts
+missing folders. The current Provider rejects explicit-null table-file imports (PVD-031). Because the SDK accepts
 arbitrary template-shaped data and cannot identify file columns without the template definition, integrations must omit
 an unset file-valued key instead of sending it as `None`. Delete means moving records into the recycle bin, not permanent
 deletion. Delete and restore return `None`; record mutations are not automatically retried.
@@ -612,8 +637,8 @@ without a readback request. Omitting `target_notebook` copies within the source
 Record patching exposes a deliberately narrower capability than the raw Provider operation. Scalar/module changes
 cannot smuggle Provider-native attachment strings; staged attachments use separate form-removal, table-replacement,
 files append/replace/remove, and rich-text types. Unsafe form replacement and table-file removal are absent, while a
-files/images removal is rejected when the observed module contains the same hash more than once (PVD-014 through
-PVD-016). The SDK reads current content only when a change needs attachment type, occurrence, row, or index state;
+files/images removal is rejected when the observed module contains the same hash more than once (PVD-010, PVD-018,
+and PVD-019). The SDK reads current content only when a change needs attachment type, occurrence, row, or index state;
 ordinary module creation and deletion rely on the Provider's own canonical update validation. `records.update()`
 returns the acknowledgement classification
 `"persisted"`, `"pending"`, or `"unknown"`; it does not
@@ -622,9 +647,9 @@ retries stay disabled. Encrypted record content is outside the SDK's public read
 `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 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.
+may also silently append at root according to PVD-030. 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
+Relation addition reads both endpoints and checks their resolved data server before writing; this reduces PVD-009
 risk but is not an atomic Provider authorization guarantee. It does not list relations merely to inspect the
 caller-relative `editable` display flag: the mutation endpoint performs the source permission check. Relation
 deletion lists current relations only to refuse an observed cross-notebook target-ID collision because the Provider
@@ -634,12 +659,12 @@ ignores target notebook identity (PVD-020); its mutation likewise performs autho
 `records.comments()`. Each returned `RecordRelationRef` carries only the relation row and declared target IDs.
 Deletion accepts the source `RecordLocator` and one of those observed refs.
 
-Comment upload follows the current Provider's literal one-request `file` field (PVD-037). Comment mutations return `None`
+Comment upload follows the current Provider's literal one-request `file` field. Comment mutations return `None`
 after acknowledgement. Edit first verifies that the selected
 comment is currently observed and caller-owned because the Provider otherwise reports a false success for a missing or
 other-user ID (PVD-004). Delete sends the typed ref directly because the Provider mutation itself enforces record and
 caller ownership. Neither operation performs a post-write read. Staged comment attachments have no Contract abort
-operation, and binding remains affected by PVD-026. Comment create/update use the same `body` vocabulary as the
+operation, and binding remains affected by PVD-003. Comment create/update use the same `body` vocabulary as the
 returned `RecordComment.body`; the SDK does not perform rich-text display normalization, while the Provider's
 documented surrounding-whitespace trim still applies when saving.
 `RecordCommentRef` carries its `RecordLocator`, so update and delete accept the ref rather than an entire comment or a
@@ -661,9 +686,9 @@ async with await client.records.download_comment_attachment(
 ```
 
 `DownloadStream` exposes status, content type, length, range, and disposition metadata without buffering the
-complete file. Streams are not automatically replayed. `ByteRange` deliberately rejects `bytes=0-0` (PVD-002).
+complete file. Streams are not automatically replayed. `ByteRange` deliberately rejects `bytes=0-0` (PVD-015).
 Comment attachment refs contain only file identity. Pass the parent comment ref returned by the same read when
-downloading; current Providers do not verify that association (PVD-038).
+downloading; current Providers do not verify that association (PVD-006).
 
 Cross-domain staging keeps resumable state and completed-file identity separate:
 
@@ -685,7 +710,7 @@ Provider URL and upload-session identity needed by internal binding and cleanup
 splice either into content. The result does not claim that a later literature/cloud operation checks the uploader or
 consumes the file exactly once. `uploads.abort()` accepts either an active `StagedUploadSession` or a completed
 `StagedFile` and exposes the Provider's legacy code-2 cancellation signal as a `None`-returning compensating cleanup
-that is not independently verified (PVD-028).
+that is not independently verified (PVD-024).
 Staging mutations are never automatically retried.
 
 Literature identities distinguish the personal library from shared libraries:
@@ -715,7 +740,7 @@ The Provider's static literature form definition and extraction deployment flag
 returns a `PublicationMetadataCandidate`: unstored, rich publication evidence rather than metadata already attached to
 a literature item. Its structured authors are `PublicationAuthorCandidate` values. Extraction accepts a DOI, a
 completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. A non-empty DOI must match
-`^10\.[0-9]+/\S+$`; the generated request model rejects other values before sending them to the Provider (PVD-042).
+`^10\.[0-9]+/\S+$`; the generated request model rejects other values before sending them to the Provider (PVD-040).
 Literature list
 results likewise exclude Provider-generated citation HTML and author-highlight fragments; Consumers receive the
 underlying citation fields instead of presentation markup. `LiteratureDetail.metadata` is `None` when invalid legacy
@@ -740,22 +765,22 @@ Create returns `None` and never guesses the new item from list position because
 canonical update preflights the raw item response and refuses to drop top-level or nested source/hidden fields. Passing
 `allow_source_metadata_loss=True` explicitly skips that preflight and sends the canonical replacement directly. The
 default read/check/write protection is best effort rather than atomic because the Provider offers no revision or
-compare-and-swap condition; this Provider-specific behavior remains internal to the update operation (PVD-027).
+compare-and-swap condition; this Provider-specific behavior remains internal to the update operation (PVD-012).
 PDF replace/delete are separate acknowledged mutations and are not presented as atomic with metadata.
 Permanent personal deletion is named `permanently_delete`, returns `None`, and is non-recoverable. Sharing requires
 list-observed item summaries, user-search summaries and a
-valid caller identity, then returns `None` because the Provider supplies no per-recipient IDs (PVD-012, PVD-036).
+valid caller identity, then returns `None` because the Provider supplies no per-recipient IDs (PVD-008, PVD-027).
 
 Literature comments use explicit `create_comment()` and `update_comment()` intents. Creation first reads the current
 detail and rejects when the caller already owns a comment; callers then use that comment's `LiteratureCommentRef` with
 `update_comment()`. The ref contains only the Provider comment-row identity. Update and delete send that identity
 directly because the Provider mutation verifies current ownership and library permission. The creation preflight
 maintains the Integration Contract's one-caller-comment invariant for ordinary SDK use, but is not atomic because the
-Provider has no matching uniqueness constraint (PVD-035). When sharing with `copy_owner_comment=True`, multiple
+Provider has no matching uniqueness constraint (PVD-026). When sharing with `copy_owner_comment=True`, multiple
 caller-owned comments remain an explicit ambiguity because the Provider would otherwise choose one implicitly. A
 staged attachment can replace one `matelab-staged-file` marker; raw temporary URLs are rejected. These checks prevent
-common misuse but do not repair the Provider's cross-user UID lookup (PVD-026). Shared-library reads and writes remain
-experimental because the Provider permission JOIN is not scoped to the current user (PVD-011); successful SDK calls
+common misuse but do not repair the Provider's cross-user UID lookup (PVD-003). Shared-library reads and writes remain
+experimental because the Provider permission JOIN is not scoped to the current user (PVD-007); successful SDK calls
 must not be treated as independent authorization proof. Literature PDF downloads reuse `DownloadStream` and the
 stable `ByteRange` subset.
 
@@ -771,16 +796,16 @@ await client.cloud_drive.bind_staged_file(staged, target=folder)
 snapshot and quota usage; pagination applies only to `files`, while request page arguments are not echoed. Personal-root
 metadata and permissions are synthetic/fixed for this Contract line and remain wire-only. File rows omit the constant
 caller owner fields and do not invent a folder location that the Provider fails to return for root-wide searches.
-Listings likewise omit search/order/direction request echoes. Ordering has no stable ID tie-breaker (PCG-003, PVD-013).
+Listings likewise omit search/order/direction request echoes. Ordering has no stable ID tie-breaker (PCG-011, PVD-038).
 Cloud files expose the nullable stored modification timestamp, not the Provider's duplicate display-formatted date and
 time strings.
 
 Folder create returns a `CloudFolderRef` built from the Provider ID. Other folder and file mutations return `None`
 after acknowledgement and do not automatically list the drive. Staged finalize accepts a completed `StagedFile`;
-the Provider binds by temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain
+the Provider binds by temporary row ID without checking its owner (PVD-002), and finalize atomicity/idempotency remain
 absent. Batch move and permanent delete do not claim Provider per-item results or atomicity. Permanent
 deletion is named `permanently_delete_files` and is non-recoverable. Cloud downloads
-resolve bytes from the final file identity and reuse `DownloadStream`, thumbnail/preview choices and the PVD-002-safe
+resolve bytes from the final file identity and reuse `DownloadStream`, thumbnail/preview choices and the PVD-015-safe
 range subset. Cloud mutations are not automatically retried.
 
 Owned, shared, and public catalog notebooks use one `NotebookRef`, distinguished by its
@@ -816,7 +841,7 @@ Template render metadata is also excluded from template summaries and record rea
 notebook title/keywords, Provider data-server routing, or the frontend PDF-capability flag. `Record.version` identifies
 historical content and is `None` for the current content. `Record.versions` contains refs usable for historical reads;
 Provider lock and signature projections remain wire-only. Relation creation still checks returned data servers
-internally to mitigate PVD-019.
+internally to mitigate PVD-009.
 
 Provider record-finalization and additional-signature mutations are intentionally outside the pinned Contract and SDK
 interface. They require the account password to unlock a private key, combine version creation with signing, provide no
@@ -920,6 +945,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.5`, commit
-`6afac7ff151680130e6e4bc6d95782589b97f4e7`, and OpenAPI SHA-256
-`31a8d03b4366e2345dfccdbbaaaccf6754b2711428afa4295d778d121988460d`.
+byte-identical wheel and source distribution hashes. The SDK Contract pin is immutable `matelab-spec v0.5.0`, commit
+`4f2959472933da47d1ea3e275552884d51d4fdd9`, and OpenAPI SHA-256
+`dee14f76e24b2d7c3d97a6f30a9369ac093d615d132db85836ab86671eadcf18`.