[Python][Table P3] Validate deferred, HTTP, and PyO3 `Table` behavior

[code-tc]

Parent: #97

Objective

Validate Python Table behavior independently across deferred authoring, HTTP execution, and the shared PyO3 kernel against the completed transactional backend.

Prerequisites

• [Python][Table P1] Port schema, serialization, bounds, and model helpers #98 and [Python][Table P2] Port fluent Table operations and writable views #100.
• Integrate transactional Table routing and SQL-style wire behavior tc-collection#9 (canonical Table routing).
• Validate transactional Table integrity, recovery, and concurrency tc-collection#10 (backend integrity contract/evidence) for final sign-off.

Test design and fixtures may proceed concurrently with backend implementation. Live HTTP/PyO3 cases remain blocked until routing is merged.

Required imperative local-host scenario

Build/install the real tinychain-local PyO3 backend and start a local TinyChain kernel/host against a temporary persisted data_dir. Using only the public Python API:

1. define a Table schema with a primary key, values, and a secondary index;
2. create/open the Table on the local host;
3. enter with tc.backend(local_kernel, mode="eager"):;
4. imperatively insert, fetch, test containment, update, upsert, filter/range, order, select, limit, count, delete, and truncate;
5. exercise writable bounded views and consume a streamed multi-block result;
6. leave/re-enter the backend context and reopen the same data_dir to prove persistence;
7. compare results and typed errors with the equivalent HTTP scenario.

Ordinary application code must not import private tinychain._local classes, construct deferred refs manually, call hidden transaction helpers, or supply transaction IDs. PyO3 must exercise the same kernel, routes, transaction ownership, persistence layout, and authorization behavior as HTTP—not a mocked or alternate Table implementation.

Test matrix

• schema and secondary-index serialization;
• create/open and metadata inspection;
• lookup, contains, count, empty, key/column metadata;
• insert/upsert/update/delete/truncate;
• bounds with exact values, slices/ranges, symbolic refs, and composed views;
• selection, ordering, limiting, streaming, and cancellation;
• duplicate key, missing key, unsupported index/order, invalid schema/value, unauthorized access, and backend structured errors;
• commit/rollback/finalize visibility observed through ordinary client calls without exposing transaction handles;
• restart/replay behavior using the same persisted data directory;
• HTTP and PyO3 equivalence for canonical requests/results/errors;
• large-result iteration with bounded client memory and no implicit full materialization.

Acceptance criteria

• Language-neutral fixtures agree between Python and the Rust route matrix.
• The required imperative local-host scenario passes using the public API and a real PyO3-backed kernel.
• HTTP and PyO3 produce equivalent logical results and typed errors.
• Deferred plans issue no network/kernel call until executed.
• Authorization denial leaks no row/schema data and performs no mutation.
• Streaming tests demonstrate backpressure/cancellation cleanup and bounded memory.
• Tests use deterministic fixtures and are reliable in unattended CI.
• Documentation contains one minimal schema/create/mutate/query example using the public API.

Validation procedure

Run focused unit tests first, then install/build the real shared PyO3 backend using the repository-documented runtime workflow. Run the imperative local-host scenario in a fresh temporary data_dir, reopen it to validate persistence, and then run the equivalent HTTP/PyO3 integration suite. Record exact commands and retain structured test output. Re-run concurrency/restart cases to detect flakes.

Tembo execution contract

automation:
  eligible: true
  executor_profile: tembo
  readiness: blocked
  primary_repository: TinyChain-Inc/client
  base_branch: main
  writable_scope:
    - py/tests/**
    - py/examples/**
    - py/README.md
    - py/tinychain/collection/**
  prerequisites:
    - "#98"
    - "#100"
    - "TinyChain-Inc/tc-collection#9"
    - "TinyChain-Inc/tc-collection#10"
  concurrency_group: python-table-validation
  required_commands:
    - "python -m pytest py/tests -q"
  external_actions: none
  draft_pr_only: true
  completion_authority: human
  visual_validation:
    required: false
    evidence: []
  budget:
    size: medium
    max_revisions: 3
    max_wall_minutes: 120