[Python][ORM] Implement Class-aware annotations, bounded mutations, and graph queries

Objective

Implement a schema-neutral ORM annotation and query system for TinyChain models, including graph-style relationship traversal, model generalization/extension, and first-class awareness of TinyChain Class definitions and instances.

The ORM must support assignment to or mutation of a Class member only when the member maps to a writable operation supported by its backing Collection, current bounded view, transaction, schema, and authorization. Python attribute syntax and generated administration must not imply that every prototype, computed, inherited, or collection-derived member is writable.

Design boundary

The ORM describes application-defined models, fields, relationships, queries, and mutations. It must not prescribe tenant business schemas or introduce another state, transaction, authorization, query, or collection engine.

Canonical foundations:

• Class state/runtime semantics: TinyChain-Inc/tc-state#9
• txfs-backed /class namespace: TinyChain-Inc/tc-server#37
• Class routing/persistence/replication: TinyChain-Inc/tc-server#34
• Python Class authoring/invocation: #35
• Final Class validation: TinyChain-Inc/tc-server#35
• Transactional Table/BTree/Tensor and other supported collection capabilities
• Generated admin/graph platform consumer: TinyChain-Inc/tcv2#63

Annotation contract

Support additive, inspectable metadata for:

• model/Class identity and inheritance/generalization
• stored members and their backing Collection path/column/key/index
• primary and alternate identities
• scalar, collection, Class-instance, relation, and nested value types
• nullable/required/default/derived/computed behavior
• one-to-one, one-to-many, many-to-one, and explicit through relationships where representable
• validation and constraints delegated to authoritative backend behavior
• read, create, update, delete, execute, and administrative capability requirements
• query/filter/order/group/traversal metadata
• admin/editor/display hints that do not grant authority
• revision, provenance, and compatibility metadata

Annotations must serialize canonically and remain separable from application data.

Class-aware member model

Every exposed Class member must be classified as one of:

1. Stored writable member — maps to an explicit supported mutation on an authoritative backing Collection.
2. Writable bounded-view member — writable only within the bounds and mutation surface of a specific collection view.
3. Stored read-only member — persisted but immutable through this ORM contract.
4. Derived/computed member — evaluated from state or a query and never directly assignable unless an explicit setter operation exists.
5. Prototype/inherited member — resolved through the Class definition; writable only if an explicit instance mutation contract maps it to backing state.
6. Method/action — executable, not assignable.
7. Relationship member — mutation follows its declared foreign-key/link/through-collection operation and cardinality rules.
8. Unsupported/opaque member — inspectable only to the degree authorized; mutation fails explicitly.

Member lookup follows the accepted Class resolution order, but mutation authority comes from the resolved instance/backing-collection contract—not merely from a prototype containing a name.

Mutation semantics

• Assignment must compile to a canonical explicit mutation plan; do not implement local Python-object mutation as if it were authoritative.
• Validate Class identity, member classification, type, bounds, schema revision, capability, and backing Collection support before dispatch.
• Use the existing kernel-owned transaction lifecycle.
• Preserve collection-specific semantics such as keys, uniqueness, indexes, bounds, sparsity, shape/dtype, writable views, compare-and-set/version checks, and supported update operators.
• Never broaden a bounded view or materialize an entire Collection to perform a member update.
• Derived, method, immutable, unsupported, out-of-bounds, stale, or unauthorized writes fail with typed actionable errors.
• Multi-member mutations are atomic only when expressed within a supported TinyChain transaction; otherwise the API must not imply atomicity.
• Inherited member assignment must resolve the effective member definition and instance storage target deterministically.
• Mutation and graph traversal must preserve tenant/Class/record authorization and avoid metadata leakage.

Query and graph semantics

• Build deferred model queries using canonical Collection operations.
• Support bounded filtering, ordering, projection, pagination, aggregation, and relationship traversal where the backing Collection provides them.
• Resolve Class generalization/extension so base-Class queries can include compatible derived instances under an explicit discriminator/identity contract.
• Permit incremental graph traversal across annotated relationships with depth, fan-out, result-size, cost, and cancellation bounds.
• Apply authorization to every record, Class, member, edge, count, aggregate, and error.
• Avoid N+1 behavior where a bounded batched/indexed query is available, without materializing unrestricted datasets.
• Do not infer relationships merely from coincidentally matching values.

Procedure

1. Read repository AGENTS.md, py/AGENTS.md, CONTRIBUTING.md, and py/ROADMAP.md.
2. Inventory existing ORM, model, annotation, collection-query, Class, and graph utilities in v1 and v2.
3. Publish a capability matrix for each supported backing Collection: readable operations, writable operations, bounded views, constraints, and unsupported cases.
4. Define canonical model, member, relationship, inheritance, query, and mutation annotations.
5. Implement Class-aware inspection and effective-member resolution using #35 rather than duplicating the object model.
6. Implement deferred query generation and explicit member mutation plans through existing Collection APIs.
7. Implement typed errors for every unsupported or unsafe mutation category.
8. Add generalization/extension queries and bounded graph traversal.
9. Add fixtures shared with generated admin/graph consumers where applicable.
10. Add one example with a base Class, derived Class, Table-backed stored members, a bounded writable view, a relationship, a derived member, and a method.
11. Validate deferred authoring first; validate live PyO3 and HTTP behavior after the Class backend prerequisites are accepted.
12. Document extension points and intentional limitations by backing Collection.

Required tests

• stored Class member read and assignment through a Table-backed instance
• multi-member transactional mutation and rollback
• inherited stored-member update
• derived/prototype/method/read-only assignment rejection
• bounded writable-view mutation inside and outside its bounds
• type, nullability, uniqueness, key/index, stale revision, and authorization failures
• relationship insert/reassign/remove under cardinality and through-collection rules
• base-Class query returning authorized compatible derived instances
• override/member-resolution consistency with the Class runtime
• bounded graph traversal, cycles, depth/fan-out limits, pagination, and cancellation
• no-materialization regression for large/streamed Collections
• deferred, real local PyO3, and HTTP parity
• concurrent mutation/conflict and retry behavior
• serialization/fixture compatibility and safe error redaction

Acceptance criteria

• ORM models can bind explicitly to TinyChain Classes and inspect effective inherited members.
• Every exposed member has a machine-readable read/write/action classification.
• Assignment to a writable Class member compiles to the authoritative backing Collection mutation.
• Mutation respects Collection bounds, schema, indexes, keys, shape/type constraints, transaction semantics, and authorization.
• Unsupported, derived, method, immutable, out-of-bounds, stale, and unauthorized writes fail explicitly.
• No mutation broadens a view or materializes a Collection unnecessarily.
• Base/derived model queries and annotated relationships work within documented bounds.
• Graph queries apply authorization and resource limits to nodes, edges, counts, paths, and aggregates.
• The same model/query/mutation definitions behave consistently in deferred, local PyO3, and HTTP modes.
• Generated-admin consumers can determine which editor/action to expose without becoming the authority.
• No tenant-domain schema or duplicate transaction/query engine is introduced.
• Required tests, typing, linting, documentation, and examples pass.

Dependencies and concurrency

• Class contract and Python authoring: TinyChain-Inc/tc-state#9 and #35.
• Canonical Class namespace/routing: TinyChain-Inc/tc-server#37 and TinyChain-Inc/tc-server#34.
• Live Class-backed acceptance: TinyChain-Inc/tc-server#35.
• Backing-Collection capability rows depend on the applicable Collection implementation and client parity issue.
• Annotation schema, capability matrix, deferred query model, and non-Class fixtures may begin concurrently with Class backend work.
• Class-aware live mutation closes only after the Class backend and at least one writable transactional Collection path are accepted.
• TinyChain-Inc/tcv2#63 consumes this issue for generated administration and graph exploration.

Non-goals

• Making every Class member writable.
• Mutating prototype/Class definitions when assigning an instance member.
• Hiding unsupported Collection operations behind client-side emulation.
• Automatic unrestricted database traversal.
• A Django-compatible API in every detail.
• Client-side authorization enforcement as a substitute for the server.
• A prescribed business-domain schema.

Start with AGENTS.md, py/AGENTS.md, CONTRIBUTING.md, and py/ROADMAP.md, then inventory the existing v1/v2 ORM, model, annotation, collection-query, Class, and graph utilities. Define the capability matrix and canonical annotations before implementing deferred queries and mutation plans; done requires the listed Class, mutation, relationship, graph, parity, error, and regression tests to pass.