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

Parent: #97

Objective

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

Prerequisites

• #98 and #100.
• TinyChain-Inc/tc-collection#9 (canonical Table routing).
• TinyChain-Inc/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

Start with the writable paths under py/tests/, py/examples/, py/README.md, and py/tinychain/collection/**. Run focused tests, then follow the repository-documented workflow to build the real PyO3 backend and run python -m pytest py/tests -q against a temporary persisted data_dir. Done means the imperative local-host scenario, HTTP/PyO3 equivalence, deferred execution, streaming, persistence, and deterministic error cases pass after prerequisites are available.