matelab-python-sdk 0.1.0a15__tar.gz → 0.1.0a17__tar.gz

matelab_python_sdk-0.1.0a17/AGENTS.md

@@ -0,0 +1,94 @@
+# AGENTS.md
+
+本文档只保留维护 `matelab-python-sdk` 必须长期遵守的约束，不记录当前功能清单、迁移历史、阶段性状态或
+一次性验收数字。
+
+## 文档与权威边界
+
+- `README.md`：当前 public interface、集成语义、示例及可执行的开发/发布流程；不承担版本迁移历史。
+- `CONTEXT.md`：公共领域术语及易混概念的统一词汇；不记录实现或协议细节。
+- `CHANGELOG.md`：按 SDK 版本记录变化和迁移影响；不作为当前接口说明。
+- `docs/operation-coverage.yaml`：operation 状态、公开入口、稳定性和已知问题的机器权威；不写叙述性用法。
+- `pyproject.toml`：SDK 版本、依赖范围、构建和工具配置的机器权威；`uv.lock` 只锁定本仓库环境。
+- `contracts/matelab-integration-v1.lock.json` 及其 snapshot：Contract pin 和 wire schema 的唯一机器权威。
+- `src/matelab/__init__.py::__all__`：公开导入边界；测试是行为证据，不替代上述文档。
+- 本文件只规定维护原则和质量门槛。机器权威变化时，同一变更必须同步受影响的叙述文档，避免复制无归属的
+  版本号、配置值或 operation 清单。
+
+## 工作范围与 public interface
+
+- 本项目是 Matelab Integration Contract 的通用异步 Python Consumer，负责隐藏 HTTP 编码、认证刷新、业务
+  错误、wire model 和 Provider 兼容细节。
+- `/home/tnzhu/projects/matelab-spec` 负责 Wire Contract、兼容策略及 Provider 问题；`matelab-server` 是 Provider
+  实现，`matelab-mcp` 只是 Consumer 证据，均不能反向定义 SDK interface。
+- 修改前执行 `git status`，现有改动视为用户工作。默认只修改本仓库；未经明确授权，不修改相邻仓库、不迁移
+  MCP、不 commit/push/tag/publish，也不对真实 Provider 执行 mutation。
+- `AsyncMatelab` 是稳定入口，能力按领域组织。public interface 只表达用户意图，不泄漏 controller、path、
+  opcode、wire 字段、generated model 或认证刷新细节。
+- 公共类型必须区分 userid、database id、UID、relation id、staging id 等身份空间。Provider 未返回的 identity、
+  affected rows、排序、分页、原子性、CAS、幂等性或持久化结果不得推测；legacy 限制应诚实表达。
+- MCP typed refs、capabilities、fingerprints、FastMCP/Redis context 和 Agent 展示模型不得进入 SDK。仅在存在真实
+  第二种实现时增加 seam，不为测试预设抽象。
+- 支持 Python 3.11+；源码不使用 `from __future__ import annotations`，前向引用优先通过定义顺序解决。
+
+## Contract、生成与 transport
+
+- 每个 operation 必须核对 pinned OpenAPI 的 request、response、security、examples 和成功码，并查看相关
+  PVD/PCG。Contract 不足时可只读参考 Provider/Consumer；仍无法安全表达就报告缺口，不猜测或静默适配漂移。
+- Contract Adoption 只能来自不可变 release tag，并在同一变更中更新唯一 lock 的 tag、commit、snapshot path
+  和 SHA-256，重新生成并复核差异；不得跟踪移动分支或改写正式 snapshot。
+- request/response 均由生成 wire model 校验，adapter 只负责 public Python 名称与 wire 字段映射。required
+  nullable 使用无默认值的 `T | None`；request 拒绝未知字段，response 兼容新增字段。
+- 不手工编辑 `_generated`。generation projection 只能补偿生成器表达能力，并保留 inherited required 及
+  `if/then`、`oneOf`、`anyOf`、`not`；生成变化必须可追溯，`--check` 必须确定、非写入且能发现 stale output。
+- `base_url` 是 Provider API 根；query、JSON、form、multipart、streaming、bearer 和成功码均按 operation 配置，
+  不能用全局默认掩盖差异。
+- `Token`、`Identity` 和 `Session` 是冻结、拒绝额外字段的 public model，组成规范化 Session JSON。每个
+  `AsyncMatelab` 最多持有一个最新 Session；SDK 不绑定裸 token，持久化、加密、撤销、身份归属和跨进程锁
+  属于集成方。不同逻辑 Session 不共享 client，但可共享注入的 `httpx.AsyncClient`。
+- token 在 repr 中隐藏，显式 Session JSON 保留凭证；凭证、SSO 参数、附件内容及敏感 payload 不得进入日志、
+  异常或提交内容。
+- access 到期前刷新；并发刷新使用单锁；安全请求遇到 `code=5` 最多刷新重试一次。mutation 默认不重试，
+  multipart/stream 仅在可重放时重试，download stream 必须可显式关闭。
+- transport、Provider business/authentication、Contract/schema 和 usage 错误必须稳定区分；公开错误直接提供
+  集成级 `category` 和保守的 `retryable`，下游不应重新解释 Provider 数字 code。
+
+## 测试与质量门槛
+
+- 测试以 public interface 为主。新增或修改 operation 至少覆盖 method/path/encoding、认证、成功映射及适用的
+  空结果、required nullable、additive response fields；通用 transport/auth/error 语义在集中测试中覆盖。
+- 删除或收紧 public interface 时同步删除过时测试；无明确兼容承诺时不保留墓碑 alias 或测试。
+- operation coverage 必须与 pinned OpenAPI exact match；implemented operation 必须同时具备 public interface、
+  wire adapter 和测试。生成测试必须覆盖 metadata/checksum、schema、required/nullable、extra policy、确定性和
+  stale detection。
+- Provider smoke 默认 skip 且不自动读取 `.env`；本地 `.env.test` 必须保持 Git ignore。只能通过显式
+  `uv run --env-file .env.test` 对已确认的隔离目标 opt in；生产目标、mutation 或带写痕迹的读取必须获得本轮
+  明确授权，并回读、尽力清理。
+- Ruff/Basedpyright 的具体配置以 `pyproject.toml` 为准；不得通过排除测试、全局关规则或缩小检查范围消除诊断。
+  Basedpyright 目标为 0 errors / 0 warnings，必要 ignore 必须精确并说明原因。
+- 先跑相关测试，交付前跑完整门槛；skip 必须说明原因，不能报告为通过：
+
+```bash
+uv sync --frozen
+uv run python scripts/generate_models.py --check
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pytest
+uv build --no-build-isolation
+```
+
+若沙箱造成缓存、Node wheel 或解释器发现失败，应在沙箱外复核同一命令，不得改配置或使用未锁定工具绕过。
+
+## 依赖、版本与发布
+
+- runtime dependency 必须声明经支持 Python 版本验证的下限，并排除未经验证的下一个 major；构建后端范围和
+  wheel package 必须显式配置，不能依赖自动发现。
+- `[project].version` 是唯一 SDK 版本源；SDK 使用 SemVer，Contract Line 不是 SDK 版本。公开接口删除、重命名、
+  类型收紧或行为变化均按 breaking change 处理。
+- 发行采用 Apache-2.0；`LICENSE`、`NOTICE`、PEP 639 metadata 和制品内容必须一致，wheel 包含 `py.typed` 且
+  不公开 `_generated`。
+- Gitee `origin` 是内部主仓库，私有 GitHub mirror 只承载 PyPI Trusted Publishing。release workflow 仅由与
+  项目版本完全匹配的 `v*` tag 触发，第三方 Action 固定不可变 commit SHA。
+- release 必须来自干净 revision、锁定环境和固定 `SOURCE_DATE_EPOCH`，记录 Contract 与制品 checksum；候选
+  制品须审计内容/METADATA、验证安装后的公开导入和类型消费、覆盖 Python 版本边界并确认可复现构建。

matelab_python_sdk-0.1.0a17/CHANGELOG.md

@@ -0,0 +1,330 @@
+# Changelog
+
+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.0a17 - 2026-08-20
+
+- Adopts immutable `matelab-spec v0.4.1` at commit `6f8ab3d14797385d0075d0aba38bf3bf529e674d` and OpenAPI
+  SHA-256 `73d899c9e60b59f9521062ffcfaaae5f073eea36f24f3e535fcb53f12242581c`. The standard wire structure is
+  unchanged from v0.4.0. PVD-041 and PCG-015 confirm that optional code-4 `errs` remains opaque, potentially sensitive
+  and unsafe to expose as a stable typed SDK interface without stronger Provider evidence and a future Contract release.
+- Breaking: `MatelabProviderError` construction now requires `provider_code`, `provider_message`, and `category`.
+  Transport and download errors preserve the Provider envelope's numeric `code` and expose an SDK-owned safe summary
+  instead of copying Provider-authored diagnostics into exceptions. The stable recovery interface remains `category`
+  plus conservative `retryable=False`; raw Provider codes are diagnostic rather than stable routing identifiers.
+  Exceptions exclude the response body, top-level `msg`, legacy `errmsg`, opaque `errs`, uncontracted debug fields, and
+  request payloads because Provider text may contain stack traces, credentials, or submitted values.
+
+## 0.1.0a16 - 2026-08-14
+
+- Breaking: `UserSummary.display_name` is renamed to `name`; the SDK exposes the Provider's raw nullable real name
+  without implying presentation formatting. `NotebookShare.recipient_display_name` similarly becomes
+  `recipient_name`.
+- Breaking: `templates.list()` now returns the `TemplateSummary` tuple directly and replaces `source` with the
+  `owned/shared/group/public` string-literal `scope`; `TemplateCollection`, `TemplateSource`, and
+  `TemplateLibraryRelationKind` are removed. Provider marketplace acquisitions and defaults share public scope, with
+  the optional user-library relation distinguishing an acquisition. The administrator-only `pending[]` queue is not
+  emitted as a visible template; owned rows expose their actual `pub` submission state as `market_review_pending`.
+  `TemplateLibraryEntryRef.kind` now identifies only the real user-library versus group-library relation identity
+  space, and one `remove_from_library()` operation replaces `unshare()`, `remove_market_acquisition()`, and
+  `remove_from_group()`. Template metadata `update()` requires all replaceable fields and returns `None`; generic
+  revision fields are renamed to `content_version`, `published_content_version`, and `market_review_reason`.
+  `TemplateMarketPage` retains its items, Provider-reported total and SDK-derived `has_more` without echoing request
+  pagination. Owned transfer provenance and pending-review publisher attribution are no longer mislabeled as
+  a uniform owner field; `owner` remains populated only where shared/group rows actually return the current owner.
+  Template summaries and marketplace entries consistently name stored usage content `usage_html`.
+  `update_usage()` replaces `update_intro()` and generates the Provider-only upload correlation value internally;
+  usage attachments remain unsupported while PVD-026 is open.
+- Breaking: removes the frontend-derived `TemplateDocument`, semantic module/field/change models, and
+  `templates.read_document()`, `save_document()`, and `patch_content()`. Template content now has one public model,
+  `TemplateModule`, read with `templates.read()` and written as a full replacement with `templates.save_content()`.
+  Consumers that provide an editor should own its layout defaults and patch model; the Provider exposes neither an
+  atomic template patch nor compare-and-swap semantics.
+- Centralizes outbound request serialization in the transport. Domain adapters now pass validated Pydantic wire models
+  directly; the transport emits wire aliases and explicitly supplied fields, reveals `SecretStr` values only in the
+  outbound payload, and separates multipart file fields without call-site `model_dump()` projections.
+- Breaking: replaces notebook sharing's raw permission masks and seven boolean update arguments with
+  `NotebookPermissions`, shared with record-page capability results. `NotebookShareRef` now contains only
+  notebook/share-row identity; recipient metadata belongs to `NotebookShare`, while caller-relative
+  `belongs_to_caller` and redundant `caller_is_owner` are removed.
+  `NotebookShares` also drops its duplicate notebook field because each share ref already carries that context.
+  The Provider signing permission remains policy-only and does not introduce an SDK signing operation.
+- Breaking: removes `NotebookListField`, notebook-list display fields and type tags from `NotebookSummary`, and UI
+  display/type-tag inputs from notebook creation and update. Provider `types`/`display`/`requests` remain wire-only
+  compatibility details; metadata updates pre-read the current owned notebook and preserve that configuration on a
+  best-effort basis because no atomic read-modify-write or compare-and-swap operation exists.
+- Breaking: removes `PublicNotebookSummary`. Owned, shared, and public catalog entries now all use `NotebookSummary`;
+  public owner/group metadata that the Contract does not return is represented as `None` rather than an empty value
+  inferred by the SDK.
+- Breaking: removes template render metadata, cloud-drive display-formatted dates, literature citation HTML/search
+  highlighting, and the Provider's literature form-definition models from the public interface. Removes
+  `literature.creation_schema()` without exposing its frontend template or deployment capability flag; Consumers call
+  `literature.extract_metadata()` directly and handle an unavailable optional backend as a Provider error. Metadata
+  extraction accepts either source and gives a supplied DOI precedence over a staged PDF.
+- Breaking: `TemplateLibraryEntryRef` drops its duplicate template identity. `TemplateSummary` no longer projects
+  owner/group display names or the Provider's UI-oriented group `admin` flag.
+- Breaking: removes `RecordSignature`, record lock/signature projections and `RecordVersionSummary`. `Record.versions`
+  now contains `RecordVersionRef` values directly; Provider version metadata and signature state remain wire-only.
+- Breaking: removes `RecordPageContext` and `RecordPagePermissions`; `RecordPage` exposes the common
+  `NotebookPermissions` directly, without duplicate input notebook, request pagination, owner display name or template
+  UI context.
+  Provider finalization and additional-signature mutations remain deliberately outside the pinned Contract and SDK.
+- Breaking: unifies personal and shared literature identities as `LiteratureLibraryRef` and `LiteratureItemRef`,
+  with `LiteratureLibraryRef.scope` derived from its identity rather than accepted as a second constructor value:
+  zero identifies the synthetic personal library and positive IDs identify shared libraries. Replaces raw literature
+  permission masks with `LiteratureLibraryPermissions`. `literature.libraries()` now returns usable summaries directly
+  and removes `LiteratureLibraries`, `PendingLiteratureShare`, and `PendingLiteratureShareComment`; dangling membership
+  rows and pending-share projections remain wire-only until a complete accept/reject Contract exists. Raw
+  source/backend extension maps remain wire-compatible but are no longer public; canonical-update loss detection stays
+  inside the update operation, covers top-level and nested source fields, and reports affected field paths only when
+  refusing a lossy update. Explicit loss opt-in skips the otherwise best-effort, non-atomic detail preflight. Comment
+  creation and update are now explicit `create_comment()` and `update_comment()` operations. `LiteratureCommentRef`
+  retains only the Provider comment-row ID. Creation pre-reads detail and rejects an existing caller-owned comment to
+  maintain the Integration Contract's one-caller-comment invariant despite the Provider's non-atomic PVD-035 gap;
+  update/delete avoid a duplicate read and rely on the mutation's ownership and permission checks. Invalid stored JSON
+  is represented by `LiteratureDetail.metadata=None` instead of a special metadata object with a wire-shaped validity
+  flag.
+  `LiteraturePage` shortens `library_name` to `name` and calls library classification labels `tags` rather than
+  overloading bibliographic `keywords`. `LiteratureLibrarySummary`, `LiteratureItemSummary`, and `LiteratureDetail`
+  use the same tag vocabulary; `literature.list(tags=...)` maps it to the legacy wire `keywords` filter.
+  Renames `LiteratureMetadata` to `LiteratureMetadataInput`, `LiteratureStoredMetadata` to
+  `StoredLiteratureMetadata`, `ExtractedLiteratureMetadata` to `PublicationMetadataCandidate`, and
+  `ExtractedLiteratureAuthor` to `PublicationAuthorCandidate`, distinguishing canonical write input, decoded stored
+  state, and unstored DOI/PDF evidence. The old public names are removed without aliases. `StoredLiteratureMetadata`
+  removes the duplicate legacy `authors` array and normalizes it into the canonical `author` text only when that
+  canonical field is absent; raw legacy fields remain available to internal update-loss detection.
+  `LiteratureItemSummary` and `LiteratureDetail` expose nullable `rating` instead of the Provider's zero-sentinel `star`,
+  represent a missing PDF as `None`, and require a non-null SHA-256 on each exposed `LiteraturePdf`; filename and size
+  remain optional. The falsely named list `publication_date` is removed, and optional list metadata uses `None` instead
+  of Provider empty-string sentinels.
+- Breaking: record export and search now return tuples directly, and routing/forwarding flags are no longer public.
+  `ExportedRecord.modules` replaces the wire-shaped `data` field and distinguishes canonical stored modules from
+  template-shaped `RecordImportItem.data`. `records.search()` accepts its required field-to-path mapping as the primary
+  positional argument; `RecordSearchMatch.values` replaces `extracted` and the redundant `missing_extractions`, with
+  absent keys distinguishing missing Provider results from explicit JSON nulls.
+  Record lists/pages omit the Provider's full UI selection/filter payload, call their free-text filter `search`, and
+  use semantic permission names; record reads accept one `RecordLocator` or `RecordVersionRef` and expose the resolved
+  locator once as `Record.source`. Owner/editable UI flags, duplicated identity, template-rendering, PDF-capability,
+  data-server, and redundant selected-UID fields are removed. `Record.version` identifies historical content. Record
+  versions retain only their typed refs; Provider version/signature metadata stays wire-only.
+  `records.import_dataset()` returns the Provider-reported database-ID tuple directly and removes the one-field
+  `RecordImportResult`. The Provider-built notebook echo in paged record responses is not revalidated because server
+  code constructs it from the request. Record update does not expose the Provider's `password` field: the pinned read
+  Contract cannot represent encrypted record content, and the frontend's separate set/change/remove-password
+  lifecycle is not a safe generic SDK capability. `RecordImportItem.keywords`
+  replaces the Provider's singular semicolon-encoded `keyword` input. The Provider's misleading record `subtype`
+  terminology is now wire-only:
+  `RecordFolder`, `folder_id`, `folder_path`, and `folders` describe the notebook directory tree. Root-parent and
+  root-record zero sentinels become `None`, empty-folder SQL counts become zero, and `NotebookPermissions` uses
+  `can_manage_record_folders`. Record identities consistently use `record_id` for the Provider database row and
+  `record_uid` for its UID; the redundant `record_database_id` spelling is removed. Record copy now accepts an
+  optional caller-chosen `new_record_uid`, generates one locally when omitted, and returns a complete
+  `RecordLocator`; the partial one-field `RecordCopyResult` is removed. Deleted-record summaries and restore inputs
+  reuse `RecordRef`; the identical `DeletedRecordRef` type is removed without an alias.
+- Breaking: replaces the eight mutation-family keyword arguments on `records.update()` with one required
+  `changes: Sequence[RecordChange]`. `RecordValueUpdate`, `RecordValueDeletion`, and `RecordModuleDeletion` complete
+  the typed intent union alongside the existing module, attachment, file-structure, and rich-text changes. The
+  category-only `RecordAttachmentChange` and `RecordFileStructureChange` aliases are removed; the SDK now keeps
+  Provider `modify`/`del`/`addModule`/`delModule`/`add` classification entirely inside the update implementation.
+  Removes `Record.content_sha256` and `records.update(expected_content_sha256=...)`: the value was only an SDK-side
+  read/prewrite comparison and could not provide Provider compare-and-swap semantics. Current-state reads now serve
+  only attachment/path safety rules; ordinary module creation and deletion use the Provider's canonical validation
+  without an additional SDK read. The update acknowledgement values are shortened to `"persisted"`, `"pending"`,
+  and `"unknown"`; the last value remains a conservative fallback for an unrecognized successful Provider message.
+- Breaking: record relations now return a tuple directly and remove `RecordRelations`; the relation endpoint's legacy
+  comment duplicate and caller-relative `editable` value remain wire-only. `RecordCommentRef` now carries its typed
+  record source, update/delete accept that ref, and `RecordComment` no longer publishes duplicate source or
+  `owned_by_caller` UI state. Comment attachment refs no longer duplicate their parent comment; downloads accept the
+  parent ref explicitly. `RecordVersionRef` likewise carries a `RecordLocator` instead of three repeated primitive
+  identity fields. Historical reads now accept that version ref
+  directly instead of requiring the same locator a second time. Public record summaries drop the unused
+  caller-ownership flag, stale publication-lock state and owner email, and use the common `notebook_title` name.
+  `RecordRelationRef` now carries only its relation row and declared target IDs. The one-use `RelatedRecordIdentity`
+  wrapper and preview-oriented `RecordRelation` are removed; `relations()` returns refs directly, while
+  `delete_relation()` takes the source locator explicitly instead of duplicating it in every listed relation.
+  Deleted-record pages do not repeat request pagination or the input notebook and impose no SDK-only size range beyond
+  the Contract minimum. Relation writes no longer list relations solely to
+  inspect the caller-relative `editable` flag; Provider mutation authorization remains authoritative, while the reads
+  required for cross-server addition and target-ID-safe deletion remain. Record comment create/update use `body`;
+  update retains the PVD-004 ownership preflight, while deletion relies on the Provider's own ownership check and
+  avoids a duplicate list request. Comment bodies are not display-normalized before the Provider's documented trim.
+- Breaking: unifies record attachment staging as `records.upload_attachment(notebook, ...) -> StagedAttachment`.
+  Uploading does not choose a target record; the handle retains its notebook selector, authenticated uploader, binding,
+  filename, and hash and is accepted by either one later import or update. `stage_attachment()`,
+  `StagedNotebookAttachment`, and `StagedRecordAttachment` are removed without aliases.
+  `upload_attachment()` no longer accepts caller-supplied staging metadata: the SDK generates the upload event,
+  calculates the SHA-256, omits the Provider's equivalent `name` and `last=1` defaults, and uses the validated response
+  as the completed staging result. Both attachment upload methods remove caller-supplied size, checksum, and multipart
+  content type because the Provider derives the metadata and both Contracts fix opaque binary attachment parts.
+  Comment uploads no longer expose `UploadBindingRef`; the SDK generates the Provider binding internally, while a
+  prior staged comment attachment may be passed as `batch=` when several uploads will be saved into one comment.
+  `RecordFilesAttachmentRootAppend`, `RecordTableFileAttachmentReplacement`, and
+  `RecordFilesAttachmentReplacement` are also removed: `RecordFilesAttachmentAppend` and
+  `RecordAttachmentReplacement` cover those intents, and files append now calls its optional location `folder_path`
+  instead of the wire-shaped `path`. Final operations centrally reject a different notebook or uploader, duplicate
+  references, and reuse after an attempted finalization. Provider temporary row IDs and caller-known response echoes
+  remain internal, while upload responses are still validated. `RecordImportItem.data` uses the recursive
+  `RecordImportValue` type instead of `object`, matching the JSON-or-staged-attachment values accepted at runtime.
+- Breaking: group discovery replaces the raw data-server selector with `notebook_creation_available`.
+  `groups.list()` now returns the `GroupSummary` tuple directly and removes `GroupCollection` and `GroupMember`; the
+  Provider's unstable first-group member projection remains wire-only. Cloud-drive listings no longer expose synthetic
+  root metadata, constant caller ownership, inferred file locations or request echoes. `CloudDriveListing` retains
+  `total_count` and SDK-derived `has_more` directly and removes the one-use `CloudFilePage` wrapper. Completed staged files
+  keep their temporary Provider URL as an internal cross-operation binding detail rather than public metadata.
+- Breaking: `StagedFile` now exposes its downstream `binding` directly instead of embedding the completed upload's
+  `StagedUploadSession`; `next_offset` remains exclusive to active sessions, while the upload-session identity remains
+  internal for cleanup. Non-final staging now returns the next `StagedUploadSession` directly and removes the shallow
+  `StagedFileFragment` wrapper. Byte fragments derive their size when omitted; file-like fragments still require it.
+  Provider-returned filename and size are still validated but no longer repeat caller-known values on the completed
+  result. `uploads.abort()` accepts either an active session or a completed staged file.
+- Simplifies notebook operation boundaries around one internal allowed-scope validator. `NotebookRef.title` rejects
+  blank values but preserves surrounding whitespace because legacy private operations use the exact title as a
+  selector. Its `Literal` already defines the three possible scope values; operation seams state whether they accept
+  owned, shared, or public refs without a redundant constructor check.
+- Makes the repository Ruff configuration authoritative for generated models. Generator emission uses its built-in
+  formatter before the explicit project-configured Ruff normalization, avoiding two competing Ruff configurations.
+
+## 0.1.0a15 - 2026-08-10
+
+- Breaking: removes `PublicNotebookRef` and uses one `NotebookRef` with `scope="owned"`, `"shared"`, or `"public"`.
+  Public `notebook_id` values identify `eln_public` catalog rows rather than source ELNs; public record results retain
+  their separate source notebook identity.
+- Centralizes notebook-scope validation: public record listing accepts only a public ref with a non-empty title,
+  private operations reject public refs, and owned-only notebook mutations reject shared/public refs. `NotebookRef.title`
+  is a non-empty `str` preserved without whitespace normalization; an unexpected null from the wider owned/shared wire
+  contract is reported as a protocol violation, matching Provider write validation and audited runtime data.
+
+## 0.1.0a14 - 2026-08-10
+
+- Adds immutable semantic template modules, editable `TemplateDocument` values, ordered name-based patch intents,
+  stable content fingerprints, and `Templates.read_document()`, `save_document()`, and `patch_content()` while
+  retaining the low-level `TemplateModule`, `read()`, and `save_content()` interface.
+
+## 0.1.0a13 - 2026-08-08
+
+- Breaking: `Identity.username` now removes surrounding whitespace and rejects values that become empty.
+- Keeps `ByteRange` typed through the transport adapter and closes the underlying HTTPX2 response when download reads
+  or iteration finish or fail, while retaining explicit `DownloadStream.aclose()` for deferred framework consumers.
+- Consolidates Provider session validation through the public `Session` models and simplifies private wire-rule and
+  token-refresh validation without changing the pinned Integration Contract.
+
+## 0.1.0a12 - 2026-08-07
+
+- Breaking: removes `MatelabAttachmentValidationError`; local attachment size and checksum mismatches now use the
+  existing `MatelabUsageError` without a separate reason/value interface.
+- Adopts immutable `matelab-spec v0.4.0` at commit `7993a7bccc213f626b9cc8124423e2b2c9e48dd7` and OpenAPI
+  SHA-256 `e725c9649700d5b4d1c7d75fb9422d64b04a68e0308ddec29ba274d774104c8e`. Fixed response models now
+  accept but ignore additive Provider fields; only the Contract's seven semantically open models preserve them.
+- Breaking: removes the unused `StagedUploadSession.new()` constructor and the caller-echoed
+  `StagedFileFragment.fragment_size` field. `uploads.stage()` now owns fresh-session creation while retaining explicit
+  restored sessions, automatic single-`bytes` checksums, and required complete checksums for resumed final fragments.
+- Breaking: removes untyped pass-through attributes from cloud-drive results, literature schema fields, and extracted
+  literature authors. Unknown response fields remain parse-compatible but are ignored unless the Contract defines an
+  open data shape. Template publication reasons now use only the Contract-declared Provider key.
+
+## 0.1.0a11 - 2026-08-05
+
+- Adds `AsyncIterable[bytes]` support to the three complete record-attachment upload interfaces without adding new
+  methods. Async content is spooled, size/checksum validated, rewound, and cleaned up without blocking the event loop;
+  `sha256` may now be omitted and computed by the SDK.
+- Adds structured `MatelabAttachmentValidationError` reasons and expected/actual values so integrations can distinguish
+  size and checksum failures without parsing exception text. Validation failures occur before Provider staging, while
+  source exceptions propagate unchanged.
+
+## 0.1.0a10 - 2026-08-05
+
+- Keeps synchronous multipart file length probes and chunk reads off the event-loop thread while preserving streamed
+  uploads, correct content length, the bytes fast path, and existing non-replay retry restrictions.
+- Replaces implicit-override suppressions with explicit `@override` declarations, simplifies inferred model attributes,
+  and declares the Python 3.11 `typing-extensions` runtime dependency directly.
+
+## 0.1.0a9 - 2026-08-04
+
+- Breaking: removes `MatelabProviderErrorKind` and `MatelabProviderError.kind`; Provider wire codes now map directly
+  to the final `MatelabErrorCategory`, which integrations consume through `MatelabError.category`. This public API
+  removal requires a subsequent SemVer-appropriate release before distribution. Operation-specific code `0`/`10`
+  success handling and the bounded code `5` authentication refresh remain unchanged.
+- Adds a conservative `retryable` flag to every public SDK error.
+
+## 0.1.0a8 - 2026-08-04
+
+- Adds a unified `MatelabErrorCategory` and conservative `retryable` flag to every public SDK error, centralizing
+  Provider error semantics so integrations no longer reinterpret `MatelabProviderErrorKind`.
+
+## 0.1.0a7 - 2026-08-04
+
+- Replaces the hand-maintained wire-validation rule tables with deterministic generated JSON Schema 2020-12 rules.
+- Simplifies transport, streaming, error mapping, and domain adapters while retaining the pinned `matelab-spec v0.3.0`
+  behavior and automatic Session refresh guarantees.
+- Breaking: tightens several public domain inputs and results, and exposes stable `MatelabProviderErrorKind` values
+  instead of raw Provider error codes.
+- Removes completed roadmap and work-package bookkeeping; refreshes release checks, documentation, and tests.
+
+## 0.1.0a6 - 2026-08-01
+
+- Adopts the immutable `matelab-spec v0.3.0` Contract release and its form-encoding updates.
+- Tightens the public authentication/session contract around complete, serializable Pydantic `Session` models while
+  retaining automatic access-token refresh and Provider SSO exchange.
+- Simplifies transport and domain interfaces, removes external-token binding and identity-attachment seams, and
+  restores strict runtime validation for byte-range inputs.
+
+## 0.1.0a5 - 2026-07-29
+
+- Adopts immutable `matelab-spec v0.1.2` at commit `6dd674ac001ae61197495ace5eba489d585cb825` and OpenAPI
+  SHA-256 `7ccaf3116c8dcec7a6e49ff51fb1a5ecc83a140e013ec600516f5c2ffb3b5378`.
+- Adds notebook-scoped staged finalizers for a null table file cell, an attachment-bearing appended table row,
+  files-module root append, and table/files occurrence replacement, with exact provenance, one-shot transport, and
+  canonical readback checks.
+- Adds typed intents for an empty file table column and complete form file-field/table file-column deletion.
+- Allows `records.update(..., module_deletions=...)` to delete a canonical module even when the current record read
+  observes attachments in it, verifies absence on persisted readback, and does not claim attachment-quote or byte
+  cleanup beyond the pinned Contract.
+- Rejects cross-scope staged attachment handles before the record read, preserving the public static types while
+  avoiding the Provider's read-audit side effect for invalid runtime input.
+- Keeps notebook-staged rich-text binding and attachment-bearing multi-record import explicitly unsupported because
+  v0.1.2 Provider Verification does not provide safe one-shot semantics for either.
+
+## 0.1.0a4 - 2026-07-28
+
+- Further reduces the alpha public surface from 150 to 126 symbols by accepting direct keyword arguments and existing
+  domain values instead of request-shaped wrapper dataclasses.
+- Centralizes safe request-model validation, strengthens generated Contract constraints, and preserves structured field
+  diagnostics without exposing credentials, tokens, or sensitive payload values.
+- Tightens Session replacement, refresh races, multipart retry safety, streaming cleanup, and exact HTTP success
+  handling while retaining stable transport, authentication, Provider, protocol, usage, and verification errors.
+- Collects all business capabilities under `matelab.domains`, keeps client/session/error/transport primitives at the
+  package root, and hardens generation and release-artifact audits.
+
+## 0.1.0a3 - 2026-07-28
+
+- Replaces HTTPX with HTTPX2 2.9.1 and raises the Pydantic compatibility floor to 2.13.4. Injected clients must now
+  be `httpx2.AsyncClient` instances; HTTPX and HTTPX2 objects are not interchangeable. Default TLS verification now
+  uses the operating system trust store.
+- Shrinks the alpha public surface from 184 to 150 symbols by returning existing domain values, tuples, booleans, or
+  `None` from simple mutations instead of defining endpoint-shaped result dataclasses. Contract invariants remain
+  documented operation semantics rather than repeated constant fields.
+- Reorganizes the record and literature implementations into domain packages and keeps generated wire imports behind
+  one private namespace without changing the generated-model boundary.
+- Aligns the opt-in SDK Provider smoke with the isolated test service's shared `MATELAB_PROVIDER_*` environment
+  variables and adds a safe `.env.example`.
+
+## 0.1.0a2 - 2026-07-27
+
+- Adopts the immutable `matelab-spec v0.1.1` release.
+- Adds notebook-scoped, uploader-bound record attachment staging before a target record exists.
+- Finalizes staged attachments through a single-record import or one new form-file-field update without exposing
+  Provider-native attachment syntax or private transport details.
+- Enforces exact notebook/user provenance and one finalization attempt per staged handle in one SDK client.
+
+## 0.1.0a1 - 2026-07-27
+
+First public alpha candidate of the asynchronous Matelab Integration Contract SDK.
+
+- Binds the immutable `matelab-spec v0.1.0` release.
+- Exposes all 71 pinned Contract operations through public domain interfaces: 15 are stable and 56 remain
+  experimental.
+- Provides instance-owned immutable Sessions, bounded token refresh, typed public models, streaming downloads,
+  and generated private wire validation.
+- Ships as a typed package for Python 3.11 through 3.14.
+- Uses the Apache License 2.0 with PEP 639 package metadata.

matelab_python_sdk-0.1.0a17/CONTEXT.md

@@ -0,0 +1,91 @@
+# Matelab SDK Domain Language
+
+This glossary distinguishes public domain concepts whose names would otherwise be easy to conflate.
+
+## Templates
+
+**Template ref**:
+The Provider database identity of one template, independent of how it appears in a user's or group's library.
+_Avoid_: Template library entry ref
+
+**Template library entry ref**:
+The relation-row identity for a template in either the authenticated user's library or a group library. User-library
+and group-library relation IDs belong to different identity spaces and select different removal operations.
+_Avoid_: Template ref, template ID
+
+**Template scope**:
+How the caller can access a template: owned, directly shared, through a group, or public. A public template's optional
+user-library relation indicates whether the caller acquired it; marketplace review is separate state, not a scope.
+_Avoid_: Template source ID, library relation kind
+
+**Template module**:
+One canonical Provider content module. Additive properties and the missing-versus-null `data` distinction are
+preserved across read/save; frontend editor defaults and Agent editing intents are not part of this model.
+_Avoid_: Template document, UI module
+
+## Literature
+
+**Literature metadata input**:
+A complete canonical set of bibliographic values proposed for creating or replacing a literature item.
+_Avoid_: Stored metadata, metadata snapshot
+
+**Stored literature metadata**:
+The bibliographic values currently stored for a literature item, including readable values that may not be accepted in
+a canonical replacement.
+_Avoid_: Metadata input, update payload
+
+**Publication metadata candidate**:
+Unstored bibliographic evidence extracted from a DOI or publication file for review and possible reuse.
+_Avoid_: Stored metadata, canonical metadata
+
+**Publication author candidate**:
+A structured author candidate supplied by publication metadata extraction.
+_Avoid_: Literature author text
+
+**Literature author text**:
+A single textual representation of a literature item's authors, whether it has one author or many.
+_Avoid_: Authors array, author list
+
+**Literature keyword**:
+A bibliographic subject term describing a literature item, independent of any library that contains the item.
+_Avoid_: Tag, library keyword
+
+**Literature tag**:
+A classification label associated with a literature item within a particular library. A library's tag set is the
+aggregate of its item tags.
+_Avoid_: Keyword, item keyword, library keyword
+
+## Records
+
+**Record ref**:
+The Provider database row identity and UID of one active or deleted record, without notebook context.
+_Avoid_: Record locator, public record ref, deleted record ref
+
+**Record locator**:
+A record ref paired with the owned or shared notebook in which it was observed. It is the complete source identity
+used by record reads and record-scoped operations.
+_Avoid_: Record ref, notebook ID
+
+**Record version ref**:
+A historical version ID bound to its record locator. It identifies observed historical content, not a separate active
+record.
+_Avoid_: Record ref, current version number
+
+**Record relation ref**:
+An observed relation-row ID and its declared target notebook/record IDs. The source locator is supplied separately to
+relation deletion; nullable joined target previews and resolved identities remain wire-only.
+_Avoid_: Relation summary, target record locator
+
+**Record folder**:
+A notebook-scoped hierarchical container used to organize records. Records at the notebook root have no folder.
+_Avoid_: Subtype, record type, template
+
+**Record import value**:
+A template-shaped value composed of JSON-compatible scalars and containers, with a staged attachment
+allowed wherever the template expects a file.
+_Avoid_: Arbitrary object, stored record module, Provider attachment reference
+
+**Staged attachment**:
+An upload prepared in a selected notebook for one later record import or update; uploading does not choose the target
+record.
+_Avoid_: Import attachment, record-scoped upload, stored attachment, attachment ref