Skip to content

Changelog

All notable changes to TypeBridge will be documented in this file.

[2.3.3] - 2026-10-27

Fixed

  • The C runtime's type_bridge_database_server_version reports the version of the connected TypeDB server. Since 2.3.1 it reported the newest version admitted by the profile, so a connection to 3.13.6 said 3.14.0.
  • TypeDB versions at or above 3.11.0 are now admitted without an upper version ceiling. Measured, supported lines remain 3.11โ€“3.14. A connection to a newer line reuses the newest measured semantic profile and protocol assumptions and warns that it is "not tested or supported by this TypeBridge release". Admission does not guarantee compatibility; versions below 3.11.0 remain refused (#286).
  • Generated SDK packages, the C runtime, and connected migrations admit 3.12.3+ on the 3.12 line for profile typedb-3.12.1/v1, and 3.13.6+, 3.14.0+, and newer lines for typedb-3.13.6/v1. Older profiles retain their line and patch-floor constraints. Measured test pins are unchanged.

[2.3.2] - 2026-10-23

Added

  • type_bridge_server::transport::v3::StagedExecutor: the staged V3 executor as a library entry for hosts that embed the server crate, the V3 counterpart of preflight_remote_request_v2 / execute_admitted_remote_request_v2. execute_staged_request takes an admitted caller and the signed request bytes and returns a StagedOutcome (signed reply bytes, code, committed / failed / unknown); /v3/staged is that call behind HTTP framing. The hook order is documented on the V3 interceptor hooks and pinned by a test.

Changed

  • TypeDB 3.14's query rules are refused at plan build on every profile and in every language (#268): a sort on a duration (query_plan_sort_unordered_value, V2 query_plan_v2_sort_unordered_value) and a range comparison of durations (query_plan_duration_range, V2 query_plan_v2_duration_range). On 3.12 and 3.13 these plans ran or crashed the server; on 3.14 they failed at the server. like/contains on non-strings were already refused (query_plan_v2_string_operator_type).

[2.3.1] - 2026-10-23

2.3.1 adds TypeDB 3.14 to the supported matrix (#268). Applications and generated packages need no change. TypeDB 3.14's stricter query rules (no sort on unordered value types, no range comparison of durations, no like/contains on non-strings) are not yet refused by the plan builder; such plans fail at the server on 3.14 and follow in a later patch.

Added

  • TypeDB 3.14 is supported: the window is 3.11โ€“3.14, and 3.14.0 is the recommended server and the default test.sh lane. A 3.14 server speaks band 9 natively and also accepts band 8, so version discovery is unchanged.
  • TypeDB 3.14 shares semantic profile typedb-3.13.6/v1: it changed no schema syntax, default or lowering. Generated packages and connected migrations on that profile run on TypeDB 3.13.6 or 3.14.0, and profile names, generated files and migration histories stay as they are.

Changed

  • Band 9 runs the official typedb-driver 3.14.0 (protocol 3.14.0), which serves TypeDB 3.12, 3.13 and 3.14. Band 8 keeps the namespaced 3.11.5 driver.
  • TypeBridge depends on typeql =3.14.0 and chrono =0.4.45. typeql pins its own chrono and regex exactly, so an application that links the TypeDB 3.14 server crates could not resolve beside TypeBridge 2.3.0 (typeql =3.13.4). The driver pin check now also requires typeql on the support window's newest line.
  • The Python typedb-driver extra accepts >=3.11,<3.15 (>=3.12.3,<3.15 on CPython 3.14).

Fixed

  • Fetched integers beyond 2^53 stay exact on every supported server; a live test now checks it. TypeBridge reads typed concept values, not the driver's JSON rendering, which rounds them in drivers before 3.14.

[2.3.0] - 2026-10-22

2.3.0 runs every query, direct or through a proxy, on one Rust pipeline, and adds staged transactions over typed query-plan/v3 programs in every SDK (#253). See the "Upgrading to 2.3" guide for the steps from 2.2.

Breaking changes

2.3.0 removes the duplicate query paths that let one query behave differently direct and through a proxy. Each entry says what to do instead.

  • Generated packages need their embedded schema authority. A package installed without one is refused with schema_authority_required. Every generator has embedded it since 2.1.0; regenerate older packages.
  • Direct queries now apply the same query limits as remote ones, because every match request, direct or remote, from a generated package or a dynamic registry, runs on one executor: a predicate nested past canonical_depth is refused with canonical_json_too_deep instead of running, and a dynamic descriptor registry no longer falls back to the old executor when a request does not fit. Raise the session's QueryLimits to run such a query.
  • QueryExecutionResourceLimits constructors in Python, TypeScript/Node, and C no longer clamp a value above the default: they keep it, and refuse a timeout past one day or more than 3 statements. Pass the values you mean.
  • Renamed Rust constants: MAX_QUERY_ITEMS, MAX_QUERY_BYTES, MAX_QUERY_GRAPH_NODES, MAX_QUERY_ATTRIBUTE_VALUES, MAX_QUERY_COLLECTION_MEMBERS, and MAX_QUERY_ROLE_PLAYERS are DEFAULT_PROXY_QUERY_*, with the same values, beside the new, larger DEFAULT_DIRECT_QUERY_*; they are defaults, no longer ceilings. The MAX_QUERY_* names remain as deprecated aliases (see Deprecated). DEFAULT_DIRECT_QUERY_TIMEOUT_MILLISECONDS, DEFAULT_PROXY_QUERY_TIMEOUT_MILLISECONDS, DEFAULT_DIRECT_QUERY_STATEMENTS, and DEFAULT_PROXY_QUERY_STATEMENTS are the defaults of the two dimensions that keep a maximum (MAX_QUERY_TIMEOUT_MILLISECONDS, MAX_QUERY_STATEMENTS).
  • ProjectedQueryMaterializationLimits::tightened is replaced by new, and the MAX_PROJECTED_QUERY_* constants are removed; materialization takes its bounds from the answer policy.
  • Changed refusal codes:
  • remote model-query preparation reports the limit that refused adaptation, such as canonical_json_too_deep with maximum_depth or query_v2_adapter_literal_byte_limit with actual_bytes and maximum_bytes, instead of query_remote_v2_model_artifact_limit;
  • a generated manager filter with more than 256 predicates is refused with structural_limit_exceeded instead of manager_filter_predicate_limit;
  • replies to authored low-level plans (query_v2_prepare_remote, queryV2PrepareRemote) are refused with query_remote_v2_* codes, and a missing executor capability with unsupported_required_capability.
  • The V1 remote envelope is removed (typebridge.query-remote-request/v1, -response/v1, -failure/v1). Authored low-level plans now travel in the typebridge.query-remote-request/v2 envelope that model queries already used; their binding API keeps its shape, and a failure carries the complete structured diagnostic. The capability advertisement and the signed outer reply are unchanged. Removed Rust API, with the *_v2 item to use instead where one exists:
  • contract: RemoteQueryRequest, RemoteQueryResponse, RemoteQueryFailure, RemoteLimits, RemoteReplyDecodeLimits, RemoteOutcome, RemoteReply, RemoteRequestFingerprint, decode_remote_reply, decode_signed_remote_failure, and the constants QUERY_REMOTE_REQUEST_FORMAT_V1, QUERY_REMOTE_RESPONSE_FORMAT_V1, QUERY_REMOTE_FAILURE_FORMAT_V1 and QUERY_REMOTE_REQUEST_CANONICALIZATION. RemoteOutcomeShape has no replacement.
  • orm: prepare_remote_query, preflight_remote_request, preflight_remote_request_at, execute_admitted_remote_request, encode_remote_request, encode_remote_request_at, check_advertised_capabilities, decode_remote_outcome, AdmittedRemoteRequest, RemoteRejection, PendingRemoteQuery and ClaimedRemoteReply.
  • orm, the V1-or-V2 dispatch: AdmittedRemoteRequestEnvelope, RemoteRejectionEnvelope, preflight_remote_request_versioned and execute_admitted_remote_request_versioned become AdmittedRemoteRequestV2, RemoteRejectionV2, preflight_remote_request_v2 and execute_admitted_remote_request_v2; RemoteRequestFormat and remote_request_format are removed, since only V2 is accepted.
  • orm RemoteReplyExpectation is a struct instead of an enum with one variant per envelope version.
  • Rust connections: SchemaPackage::connect(policy) takes a DirectConnectionPolicy or a ProxyConnectionPolicy and returns Connection<S> (Direct(Database<S>) or Proxy(ProxyDatabase<S>)) instead of Database<S>; match Connection::Direct for CRUD managers. Renamed: RemoteDatabase to ProxyDatabase, RemoteQueryTransport to ProxyExchange, RemoteConnectionOptions to ProxyConnectionPolicy (generated(limits, transport) is with_exchange(transport).answer_limits(limits); new(scope, profile, limits, transport) adds .authority(scope, profile)), and DirectTls to TlsPolicy; pass QueryExecutionResourceLimits where 2.2 took RemoteQueryLimits. The 2.2 names remain as deprecated aliases (see Deprecated), so 2.2 RemoteDatabase code compiles. What breaks is the Connection<S> return of connect and of connect_with_cancellation; both take impl Into<ConnectionPolicy>, and connect_with_cancellation no longer needs the typedb feature.
  • Two exhaustive enums gain a Complete variant for the new complete row cardinality: orm match_request::RowCardinality and contract query_plan::QueryRowCardinalityV2. Add an arm to a match over them.
  • The server's config::V2Section gains the public fields query_limits, answer_limits and allow_unauthenticated_staged_writes. A struct literal needs them or ..Default::default(); TOML configuration is unaffected.
  • Generated Python packages have one async session. QuerySession, Query, and GroupedQuery run on every connection, and every terminal (one, first, rows, page_by, count_by, exists_by, aggregate, grouped aggregate) is a coroutine, direct included; composition stays synchronous. QuerySession(connection, *, resources, cancellation, query_limits) takes the connection first and no projection, and Model.query(connection, ...) accepts the same options. Removed: QuerySession.remote_factory and the native PyRuntimeProjection.match_session() (use match_session_with_resources); the 2.2 remote names remain as deprecated aliases (see Deprecated). To migrate:
  • await each terminal; a script without an event loop wraps the session in type_bridge_core.blocking(session), which runs each terminal to completion on a private thread.
  • RemoteQuerySession(advertisement, exchange, limits) becomes QuerySession(ExchangeConnection(advertisement, exchange), resources=limits), or QuerySession(connect_proxy(url)) for the built-in HTTP route. RemoteQueryLimits(max_items=..., ...) becomes QueryExecutionResourceLimits(items=..., ...); its defaults are the statement count and deadline the flat limits used.
  • The handwritten Python typed-query facade type_bridge.typed is removed: QuerySession, Query, RemoteQuerySession, RemoteQuery, RemoteQueryExchange, RemoteQueryLimits, Page, BoundVar, BoundField, BoundRole, Collected, Predicate, QueryOrder, Selection, FieldRef, RoleRef, TypedQueryCapabilityError, TypedQueryConnectionError, TypedQueryMaterializationError, and TypedQueryWindowError. The generated packages' 2.2 remote names stay as deprecated aliases (see Deprecated). Use the generated package's own QuerySession, Query, and tokens (from your_generated_package import Query, QuerySession); every terminal is awaited, and a script without an event loop wraps the session in type_bridge_core.blocking(session). Generated model stubs import their static descriptor protocols from type_bridge.fields._generated_descriptors; a package generated earlier still runs, but a type checker reports the missing module until it is regenerated. Removed with it, from type_bridge_core: the flat-limit query_v2_remote_model_context (use query_v2_remote_model_context_with_resources), revalidate_match_diagnostic, and validate_match_order_term_count.
  • Rust: ast::FetchItem gains Raw(String) for raw fetch entries; an exhaustive match on it needs that arm.
  • Generated TypeScript packages have one session. QuerySession, Query, and GroupedQuery run on every connection, and every terminal (one, first, rows, pageBy, countBy, existsBy, aggregate, grouped aggregate) returns a Promise, direct included; composition stays synchronous, and direct terminals no longer block the event loop. new QuerySession(connection, { resources, cancellation, queryLimits }) takes a RustDatabase, a transaction, a ProxyConnection, or an ExchangeConnection; the 2.2 remote names remain as deprecated aliases (see Deprecated). Removed from @type-bridge/node/runtime-projection: RuntimeProjectionRemoteLimits, the seven InstalledRuntimeProjection.execute* methods (use direct(connection)), and the natives matchSession() without resources and the flat-limit queryV2RemoteModelContext (use matchSessionWithResources and queryV2RemoteModelContextWithResources). To migrate:
  • await each terminal.
  • new RemoteQuerySession(advertisement, exchange, limits) becomes new QuerySession(new ExchangeConnection(advertisement, exchange), { resources }), or new QuerySession(await connectProxy(url)) for the built-in HTTP route. Flat limits { maxItems, maxBytes, ..., deadlineMs } become new QueryExecutionResourceLimits({ items, bytes, ..., timeoutMilliseconds }).
  • Generated Python and TypeScript packages no longer check query windows, selection and aggregate caps, group-by keys, or reachability depth themselves; the Rust core refuses them with its structured diagnostic (in Python InvalidQueryRequestError, still a ValueError; in TypeScript the structured error with category and code), the same on every connection. TypeScript callers catch the core codes instead of the old host errors:
  • a zero limit is zero_window_limit and an offset plus limit past the unsigned 64-bit range is window_overflow (TypeScript accepted limit: 0n and now refuses it);
  • more selections than selected_slots is selection_cap_exceeded, no or too many aggregate terms are empty_reducers / reducer_cap_exceeded, and too many group-by fields are field_group_tuple_cap_exceeded, still raised by group_by() / groupBy() (TypeScript raised RangeError);
  • a reachability minimum depth above its maximum is reachable_bounds, and a maximum above the predicate-depth ceiling (64) is reachable_depth_limit.

The caps follow the session's QueryLimits: a session that lowers selected_slots is refused at its own limit, where the hosts used to apply a fixed sixteen. Marshalling stays a host error with the 2.2 classes in Python: a malformed window (a bool, a non-int, or a value outside the unsigned 64-bit range) raises ValueError, and a depth that is not an int raises TypeError or outside 0 to 255 ValueError; in Node a window that is not a u64 bigint or a depth that is not an integer from 0 to 255 is a native argument error (it was a RangeError). These are the same on every connection: a caller-exchanged session no longer reports a malformed window as query_remote_limit_invalid.

C query descriptors get the same codes instead of c_query_descriptor_layout_invalid for a zero limit, no selected slots (empty_output) or reducers, a slot, order, group-field, or reducer table above the core's ceiling, and an invalid output name (invalid_output_name); a terminal now accepts up to 64 order terms, the core's limit, instead of 16. - Every enum the native modules accept as text (comparison operator, sort direction, missing-key order, row cardinality, reducer, transaction type, value type, record kind, manager lookup and comparison, owner lookup, match mode, given-row column type) is parsed by the Rust core. An unknown spelling is one structured diagnostic in every language: category invalid_input, code unknown_enum_value, details kind, accepted, and value (the rejected text, left out when it is not a bounded identifier). Python raises the new type_bridge_core.UnknownEnumValueError, a subclass of both MatchRequestError and ValueError, so except ValueError still catches it; TypeScript raises the structured error with that code instead of a plain native argument error. The old message texts are gone. As in 2.2, transaction types are trimmed and ASCII case-folded (" READ " opens a read transaction), and Node compareValueJson / functionValueJson accept the TypeQL spelling datetime-tz as an alias of the scalar domain datetime_tz. Accepted spellings changed: - row cardinality also accepts complete, which the core validates; - TypeScript QuerySession.var(model, mode) refuses a mode other than exact or subtypes with the structured error (was TypeError); the native match session's new binding(typeName, matchMode) parses it; - Python execute_with_rows column types are boolean, integer (alias long), double, string, date, datetime, and datetime-tz; any other raises UnknownEnumValueError before a row is read (was a ValueError naming the row); - the manager lookup aliases exact (for eq) and like (for regex) and the owner lookup alias exact remain, now defined by the core.

The low-level query-v2 builders (Python and Node) report an unknown value type, type kind, comparator, order direction, or reducer the same way, with code unknown_enum_value and the same details; the category stays invalid_contract, like every builder refusal. The codes query_builder_value_type_unknown, query_builder_type_kind_unknown, query_builder_comparator_unknown, query_builder_order_direction_unknown, and query_builder_reducer_unknown are gone.

Rust: ValueType::parse (returned Option) is replaced by str::parse::<ValueType>(); the core enums gain FromStr, ACCEPTED, KIND, and spelling(), and ValueType / ValueTypeTag convert with From. - A structured SDK diagnostic reaches Python and Node in one JSON form, defined by the Rust core (SdkExecutionDiagnostic::host_json): version, category, sdk_category, query_category, code, message, path, details. In the JSON form count, byte_count, and signed detail values are decimal strings, because a u64/i64 does not fit a JavaScript number; path positions (index, output_slot, binding, role_edge) stay numbers. - Python: MatchRequestError (and UnknownEnumValueError) keep their classes and attribute names, and count, byte_count, and signed detail values stay int, as in 2.2. The exception gains a version attribute. - Node: the native error message of a structured diagnostic uses the keys sdk_category and query_category (was sdkCategory, queryCategory) and adds version. QueryV2Error properties are unchanged. TypeScript no longer re-validates the native JSON field by field; it takes the core's form as given (internal failures still stay plain errors). - Rust and C are unchanged: the C ABI keeps its typed accessors, and its contract diagnostic JSON is the same serde form Python and Node give a QueryV2Error.

The cases in tests/contracts/diagnostic-json.json are checked to be identical in Rust, Python, Node, and C (for the cases C can produce). - Generated Python and TypeScript packages no longer check a model member's cardinality themselves; the Rust core checks it at the same call (Python field assignment and construction, TypeScript create and decodeCreate) with the rule and codes encoding uses: no value for a required member is missing_required_field / missing_required_role, any other count outside the cardinality is field_cardinality_violation / role_cardinality_violation, with actual_count, minimum_count, and maximum_count details. - Python raises the new type_bridge_core.ProjectedCardinalityError, a subclass of both MatchRequestError and ValueError, so except ValueError still catches it; the old message texts are gone. - TypeScript raises the structured error with that code instead of a RangeError. Hydrated values are no longer re-checked in TypeScript; the core checked them when it hydrated them. - A provider row whose member count is outside the projected cardinality is refused by the core with the same codes in category integrity (Python MatchRequestError, Node the structured error) instead of a RuntimeError reading "provider row violates projected cardinality". - A generated manager write (insert, put, update, and their batch forms) whose model holds a member count outside the cardinality, such as a hand-built Node wire, is refused by the core with the same codes in category invalid_input (Python ProjectedCardinalityError, Node the structured error) instead of a ValueError reading "projected value violates resolved cardinality" or a Node error reading "projected member violates resolved cardinality". - Mixed versions: clients and executors must both be 2.3. - A 2.3 executor refuses a V1-format request with query_remote_v2_format_unsupported and a supported detail naming the accepted format. - A 2.3 client prepares authored plans only for an executor that advertises query.plan.v2, query.remote.envelope-v2, and query.remote.structured-diagnostic. - A client older than 2.3 cannot decode the advertisement of an executor configured with non-default query or answer limits.

Added

  • TypeDB 3.13 servers are supported for queries and CRUD. The support window is 3.11.0โ€“3.13.x; 3.13 servers negotiate the band-9 driver and use the semantic profile typedb-3.13.6/v1. Generated packages on that profile connect to exactly TypeDB 3.13.6. TypeDB 3.14 and newer are refused. A connection whose band-8 discovery probe finds a 3.13 server reconnects on band 9 instead of refusing it.
  • Connected migrations (migration apply, verify, adopt, and rollback) run on TypeDB 3.13.6 with the workspace profile typedb-3.13.6/v1. Each profile runs on exactly one server: typedb-3.12.1/v1 on 3.12.3 and typedb-3.13.6/v1 on 3.13.6; any other pair is refused with migration_typedb_server_version_unsupported, which names the server the profile expects, and any other profile with migration_typedb_semantic_profile_unsupported before credentials or the filesystem are touched. An existing 3.12 history moves to the new profile with migration upgrade-profile --to typedb-3.13.6/v1 (below). require_supported_migration_server_for_profile, require_supported_migration_profile, and migration_server_for_profile in type_bridge_schema_migration_typedb expose the pairing.
  • type-bridge migration upgrade-profile --environment <env> --to typedb-3.13.6/v1 moves a migration history to a newer TypeDB line. After the databases are moved to the new server and compatibility.semantic-profile names the new profile, it writes one zero-operation profile bridge manifest and records it in that environment's ledger. It requires the ledger at the history head and the live schema unchanged (migration_upgrade_profile_live_drift), is idempotent, and cannot be rolled back (migration_rollback_profile_bridge). migration make, plan, apply, and verify on a history still on the older profile refuse with migration_history_profile_upgrade_required and print the command to run. A bridged history also replays into a new, empty database on the newer server: migration apply applies the older migrations under their own profile, the bridge as a profile flip, then the newer ones, all verified. Older-profile migrations are refused anywhere else.
  • typebridge.query-plan/v3, an open canonical plan format for one typed TypeQL pipeline: an optional match with comparisons and let values (typed arithmetic and builtin expressions, checked against TypeDB numeric rules), bounded given input rows, insert, put, update and delete write stages, and a read (Rows, Count, Exists) or write operation. A plan is validated against schema authority (write targets, concrete types, ownerships, roles, key immutability, binding lifetimes). Rust owns the canonical bytes and every SDK calls it, so one program has the same bytes in every language; released V2 read plans lift into V3 without changing their representation. The format, its capabilities and the staged envelope are specified in the Query-plan V3 reference.
  • query-plan/v3 match stages accept an iid pattern that identifies an already typed entity or relation binding by its canonical IID (query.pattern.iid).
  • query-plan/v3 gains a terminal fetch stage that answers a thing's hydration document (IID, exact type, owned attributes, and the players of listed roles) in the same pipeline (query.fetch.thing, not yet advertised by proxies).
  • query-plan/v3 gains an attach write stage that adds an ownership value or a role player to an already bound thing, keeping the existing ones (query.write.attach, not yet advertised by proxies).
  • Conditional writes in one transaction. A query-plan/v3 write plan puts its checks (where comparisons, let values) and its writes in one TypeQL pipeline, and a staged transaction commits all its staged plans atomically: a failing plan stores nothing, and a lost race is a typed conflict failure (Python CommitConflict) to rerun when retry_safe is true. A condition that matches nothing is not an error: the commit succeeds and the plan answers Matched(0), so check the answer. See Concurrency and conditional writes for the purchase example in every SDK, and Checkout: a whole cart in one query for a cart whose stock checks, total, balance check and writes are one plan (#253).
  • query-plan/v3 delete stages gain DeleteItem::Players { relation, role }, which removes every player of a role, so a relation update can clear a role and attach its new players in one plan. DeleteItem, AttachItem and Stage are non_exhaustive.
  • Rust staged transactions run query-plan/v3 programs and typed reads. Transaction::stage_plan lowers a plan to one provider query when it is staged and resolves to a PlanAnswer (Rows, Count, Exists or Matched) only after the commit succeeds; plan inputs need the TypeDB 3.12+ given stage. Transaction::stage_match stages a validated typed read, including in a Write transaction, where it sees the writes staged before it. Staged reads honour the transaction's answer limits, deadline and cancellation. A Schema transaction refuses both with borrowed_target_not_read_only.
  • The Rust SDK builds typed query-plan/v3 programs and stages them. type_bridge::plan::Plan::builder() declares things (exact, subtypes), field values (field), inputs and input rows (input, row), comparisons (where_), role links (links) and let values from generated model, field and role tokens, then update, insert, put and delete writes; build(&SCHEMA) validates it against the generated package. Database::transaction(TransactionOptions) returns type_bridge::staged::Transaction with stage, commit, rollback and close; nothing opens before commit. ProxyDatabase::transaction returns the same type, and commit and pending-answer errors convert into type_bridge::Error. The rules that number handles, order terms and name variables live in the contract's query_plan::v3::PlanBuilder, so a program has one canonical encoding.
  • Python builds the same plans with type_bridge.plan.Plan.builder() (where_, let_, and otherwise the Rust names in snake_case) from generated model, field and role tokens; build(schema_authority()) validates it, and generated Python packages export schema_authority(). Database.staged_transaction(kind=None, *, commit_on_exit=True) and RustDatabase.staged_transaction open a direct staged transaction beside the released transaction(); it and ProxyConnection.transaction stage built plans and answer typed Rows, Count, Exists or Matched values from Pending.result().
  • TypeScript builds the same plans with Plan.builder() from @type-bridge/node (exact, subtypes, field, input, optionalInput, where, links, let, update, updatePlayer, insert, put, delete, deleteField, deletePlayer, row, returning, count, exists, then build(authority)) from generated model, field and role tokens; a token of another model is a type error. RustDatabase.stagedTransaction(kind) opens a direct staged transaction with stage(plan), commit, rollback, close, and an async dispose that closes without committing (await using). Generated packages export schemaAuthority(). RustDatabase.transaction(kind) keeps its released eager context.
  • C ABI 1.7, a strict superset of 1.6: every 1.6 symbol keeps its behaviour. It adds:
  • staged transactions over query-plan/v3 plans: type_bridge_plan_v3_decode (canonical plan bytes under declared schema bytes), type_bridge_database_transaction, type_bridge_proxy_connection_transaction, type_bridge_staged_transaction_{stage,commit,rollback,close} and type_bridge_pending_answer. As in the other SDKs, the handle is a reusable logical transaction: commit and rollback take it by pointer and keep it usable, and close is the only release;
  • the plan builder (type_bridge_plan_builder_*), which forwards to the core builder, so a C program has the same plan bytes as any other SDK;
  • type_bridge_execution_diagnostics_failure_get_v1, which reads a typed failure (outcome, phase, reason, lock kind, annotation, retry_safe, staged op_index, provider code) into type_bridge_execution_failure_v1_t;
  • type_bridge_write_transaction_rollback_keep;
  • the TYPE_BRIDGE_DEPRECATED(msg) header macro, not yet applied.

Schema package descriptors of ABI 1.6 and 1.7 are both accepted. The installed CMake package reports ABI 1.7.0 and accepts 1.6 and 1.7 requests, EXACT included, so find_package(TypeBridge 1.6.0 EXACT) keeps resolving and find_package(TypeBridge 1.7) requires the new minor. pkg-config keeps Version: 1.6.0 for exact pins and provides type-bridge-abi = 1.7.0 (Requires: type-bridge-abi >= 1.7.0). - Staged transactions cross the proxy. ProxyDatabase::transaction (Rust), ProxyConnection.transaction(kind) (Python and TypeScript) and type_bridge_proxy_connection_transaction (C) return the same staged transaction: commit sends every staged plan in one typebridge.query-remote-request/v3 envelope to POST /v3/staged, verifies the signed reply, and resolves the answers and typed failures direct execution gives. The server keeps no replies: a lost or unverifiable reply is commit_outcome_unknown, as a lost direct commit is, and the application reads the database to learn whether it applied. The server runs each request at most once; resent bytes are refused, as commit_outcome_unknown for a write. Only plans stage over the proxy; raw TypeQL and stage_match are refused with staged_proxy_unsupported. - The TypeBridge server runs staged query-plan/v3 transactions at POST /v3/staged and advertises them at GET /v3/capabilities. Every configured interceptor must declare supports_v3, or each V3 request is refused with query_remote_policy_rejected. A write transaction needs an interceptor to vouch for the caller through on_v3_write_authority, unless [v2] allow_unauthenticated_staged_writes = true (default false); otherwise it is refused with staged_write_not_authorized. - Server interceptors can authorize each staged plan with on_v3_plan, which sees a redacted V3PolicyPlan (capabilities, touched types, operation, writes; input rows only when wants_v3_plan_rows opts in) and refuses the whole request before anything is reserved or opened, and can observe each staged transaction's outcome with on_v3_commit (V3CommitOutcome: committed, code, commit certainty, typed failure). Both default to no-ops. - Typed provider failures. Every query and commit failure is classified once, from TypeDB's error code and fixed message text, into a value-free Failure: Rejected (definitely not stored, with phase query or commit, a reason, and the staged op_index) or Indeterminate (the commit may have applied). Reasons are a conflict with its lock kind (exclusive, require_deleted_key, deleting_required_key, unknown), cardinality, uniqueness, a constraint with its annotation, or another code. retry_safe says whether rerunning the whole transaction on a fresh snapshot is safe; an indeterminate commit must be reconciled first. The winner of a conflict is not reported: TypeDB does not expose it. - Rust: error.failure() on type_bridge::Error and the ORM, runtime and server errors, in the type_bridge::failure vocabulary. - Python: an immutable error.failure (phase, reason, lock_kind, annotation, op_index, retry_safe, code). Commit errors raise type_bridge.CommitRejected, its subclass CommitConflict, or CommitOutcomeUnknown, all RuntimeError subclasses, from released and staged commits alike; staged pending answers that observe the commit outcome raise the same class, while staged query-phase failures keep MatchRequestError. - TypeScript: readonly failure on QueryV2Error. - C: ABI 1.6 keeps its statuses (TYPE_BRIDGE_STATUS_EXECUTION_FAILED, TYPE_BRIDGE_STATUS_COMMIT_OUTCOME_UNKNOWN), now chosen from the typed outcome, and its released detail set; ABI 1.7 reads the failure through its accessor. - Server: HTTP error.details carry the failure.

Diagnostics keep their released codes and add the details retry_safe, code, rejection, lock_kind and annotation. - One connection, direct or proxy, chosen by configuration, in every language; the same query program runs on either and returns the same results and refusals. A proxy connection uses a built-in HTTP route to a TypeBridge server's /v2/capabilities and /v2/query over plaintext or TLS (native roots or a custom root bundle), with optional request headers such as Authorization and an optionally pinned advertisement; it follows no redirects and ignores proxy environment variables. Every proxy connection takes an answer-limit ceiling. - Rust: SchemaPackage::connect(policy) with ProxyConnectionPolicy::new(ProxyEndpoint::new(url)) (TlsPolicy), or ProxyConnectionPolicy::with_exchange for a host-owned ProxyExchange. - Python: connect_proxy(endpoint, ...), or ExchangeConnection(advertisement, exchange, *, answer_limits=None) for a host-owned exchange; pass either to QuerySession or Model.query. The native ProxyConnection behind it has execute_*_proxy terminals. - TypeScript: connectProxy(endpoint, options) resolves to a ProxyConnection, and new ExchangeConnection(advertisement, exchange, { answerLimits }) is the host-owned exchange; pass either to QuerySession. - C: type_bridge_proxy_connection_open_v1 opens a synchronous connection from type_bridge_proxy_connection_options_v1_t (endpoint, TLS mode and custom root, headers, pinned advertisement, connection and answer limits), and type_bridge_proxy_query_execute_v1 runs a terminal on it with the same arguments and result family as type_bridge_database_query_execute_v1. Generated C packages emit {prefix}_proxy_query_execute_{kind}. The remote context stays as the exchange extension point for hosts that own the route. These entry points and types are new in ABI 1.7; the 2.2.6 (ABI 1.6) header does not declare them. Generated packages that call them carry an ABI 1.7 descriptor, and their CMake and pkg-config files require ABI 1.7 (find_package(TypeBridge 1.7.0 EXACT), type-bridge-abi >= 1.7.0), so a 2.2.6 runtime is refused at build time. - Configurable query limits. QueryLimits replaces the fixed ceilings on a query's encoded size, nesting depth, and structure, and a session can lower or raise them, including plans larger than 16 MiB. Python, TypeScript/Node, and Rust sessions accept it (query_limits, queryLimits, with_query_limits); C ABI 1.7 adds type_bridge_query_limit_override_v1_t and type_bridge_query_session_open_with_limits_v1. Defaults are unchanged. - Remote executors advertise the query limits and answer ceilings they enforce. A client holds a request to the stricter of its own and the advertised limits, refuses a query limit before sending, and asks for no more answer than was advertised. The standalone server reads [v2.query_limits] and [v2.answer_limits]. - Configurable answer limits. How much a query may return is one policy, QueryExecutionResourceLimits, on both transports. A caller may raise a dimension as well as tighten it: more than its transport's default can be returned when the session, and through a proxy the executor too, are configured for it. Only timeout_milliseconds (one day) and statements (3) have a supported maximum; a value past it is refused by name. - Query-limit and answer-limit refusals report limit, maximum, and source (default, configured, or advertised). - type_bridge_core.DEFAULT_DIRECT_QUERY_* and type_bridge_core.DEFAULT_PROXY_QUERY_* (TIMEOUT_MILLISECONDS, ITEMS, BYTES, GRAPH_NODES, ATTRIBUTE_VALUES, COLLECTION_MEMBERS, ROLE_PLAYERS, STATEMENTS), and the same names on the native Node module: the answer-limit defaults of each transport, read from the Rust core. The TypeScript package no longer carries its own copies of these defaults or of the codec byte ceilings; an omitted QueryExecutionResourceLimits dimension takes the core default in every language. - type_bridge_core.InvalidQueryRequestError, a subclass of both MatchRequestError and ValueError, for the query refusals 2.2 raised as ValueError (codes zero_window_limit, window_overflow, selection_cap_exceeded, empty_reducers, reducer_cap_exceeded, field_group_tuple_cap_exceeded, reachable_bounds, reachable_depth_limit), so except ValueError still catches them. Python exception details keep int counts; only the JSON form uses strings. - type_bridge_core.canonical_enum_spelling(kind, value) and the native Node canonicalEnumSpelling(kind, value): check a spelling against the core enum named by kind and return its canonical spelling (exact becomes eq). Generated Python owner lookups (has(), owners()) use it instead of their own list. The cases in tests/contracts/enum-spellings.json are checked in Rust, Python, and Node; C checks that its integer constants spell the same enums. - The core's TypeQL compiler renders any single legacy node: QueryCompiler::try_compile_node over the new ast::QueryNode, and a raw fetch entry ast::FetchItem::Raw. The String-returning compile_node, compile_pattern, compile_statement, compile_constraint, and compile_value are public for bridging only and deprecated on arrival (see Deprecated). Python's native QueryCompiler.compile_node(dict) takes the tagged node form. - type_bridge_core.blocking(obj): a blocking view of an object with coroutine methods, such as a generated session, for code without an event loop. - A complete row cardinality in the request model and the V2 plan: every distinct selected row, or a refusal when there are more than the limit. It needs no order and no unique key. Plans that use it require the new query.operation.complete-rows capability, which an executor older than this release does not advertise. - The pipeline stages emit field-free tracing spans a subscriber can time: tb.orm.plan (plan build and staging), tb.query.compile (lowering and rendering), tb.runtime.execute, tb.commit and tb.decode. They record no query text or values; with no subscriber a span costs one callsite check.

Changed

  • A successful rollback keeps the transaction usable: the writes are discarded, and more work can run and be committed on the same transaction until close(). This holds for Python and TypeScript transaction contexts (a Python with block commits work done after an explicit rollback when it exits normally) and for the staged transaction in every SDK. Rust WriteTransaction::rollback(self) and C ABI 1.6 type_bridge_write_transaction_rollback still consume the transaction; use the new WriteTransaction::rollback_keep(&mut self) and ABI 1.7 type_bridge_write_transaction_rollback_keep to keep it.
  • TypeDB-origin errors now expose a bracketed code and fixed description instead of provider prose, including ordinary SDK errors, debug output, HTTP messages, migration diagnostics and Rust source chains. Existing exception ancestry, error variants, HTTP statuses and C ABI 1.6 statuses are preserved. Query values, credentials and endpoint text are excluded. Locally authored validation and application transport errors retain their existing messages.
  • TypeDB transport failures keep a fixed failure kind and the operation name.
  • A close failure after a successful commit is logged and no longer reported as an error: the write is durable, and reporting failure invited duplicate retries.
  • Schema generation, TOML conversion, migration statements, V2 read plans, local functions, bounded fetch lists and prepared control reads render through the official TypeQL AST. Whitespace, stage separators, block indentation, capability commas, fetch objects and numeric spelling follow its plain display form; plan bytes and ordered given rows are unchanged. Snapshots, migration sources, carried queries, caller-owned function bodies and checksums keep their original bytes; new artifacts hash their new rendered bytes. Updates use the TypeQL 3 equality constraint.
  • Active schema and query parsers use the official grammar and refuse unofficial syntax or constructs legacy nodes cannot hold; empty legacy input still parses to an empty clause list. The deprecated archive reader keeps released inputs until 3.0. Checked lowering refuses non-Has relation attributes and ownership deletes whose attribute type it cannot retain.
  • Retained Python schema, migration, CRUD and query helpers pass typed metadata to Rust for rendering; their signatures are unchanged.
  • TOML function bodies the official parser rejects report MalformedFunctionBody.
  • Ordered ownership and role lists in live schemas are read through the official AST. List drift reports migration_typedb_observation_no_candidate_match instead of migration_typedb_export_invalid, while refusing the migration.
  • The published type-bridge-orm and type-bridge-schema-compat crates pin typeql =3.13.4 (was =3.12.0).
  • Generated manager writes that go through the projected executor run as query-plan/v3 write plans; the next entries describe them. Where they go through it:
  • Rust SDK: single insert, put, update and delete in every generated package; batches (*_many) only in packages generated with ordered collections (projection handler version 2).
  • C SDK: every single write and batch in every package; C has no handler gate.
  • Python and TypeScript/Node: single writes and batches only in packages generated with ordered collections (handler version 2). A TypeScript single delete keeps the released path in every package.
  • The exceptions each entry names (ordered models, relation puts) keep the released path inside the executor.

Packages generated without ordered collections carry handler version 1, and the handler version is the package's behaviour version. In 2.3 those packages keep the released write path in Python and TypeScript (every write) and for Rust batches, because routing them would change error classes, rollback-only latching and batch limits without a regeneration. Routing them to plans is a later opt-in (a handler bump on regeneration, or 3.0). - A projected relation insert resolves its role-player references inside the write: each reference is an exact isa! match, or a disjunction over the concrete candidate types, in the insert's own pipeline, so no lookup query runs first. A reference that matches nothing still fails with provider_identity_cardinality_invalid and writes nothing. A polymorphic reference that matches several things, and two references of one role that resolve to one player (duplicate_resolved_role_player), are now refused after the write instead of before it. - A projected entity put with a key value is one write: it puts the key on exactly the declared type, clears the non-key fields the input omits and updates the given ones in the same pipeline, so no key lookup runs first. A multi-valued field it gives is emptied and its values attached in the same plan. A put on a model with an ordered field, and every relation put, still look the key up first. - Projected entity insert, update and delete, and relation update and delete, are each one write plan; inserts and updates answer their own hydration document, so no read-back follows. Updates keep the complete replacement: every non-key field (and, for a relation, every role) is cleared and the given values and players attached, references resolved in the same plan. Inserts and updates on models with ordered fields or roles, and relation updates without players, keep the released path; every delete that reaches the executor runs as a plan. For the Rust SDK single insert, provider answers that do not describe exactly one canonical thing now report missing_post_write_row, provider_identity_cardinality_invalid or provider_identity_mismatch instead of invalid_provider_evidence. - When a projected insert, update, keyed put or delete (entity or relation) fails after its write plan was dispatched (including hydration), a borrowed transaction is now rollback-only. A plan that could not be lowered reached no provider and latches nothing. - A projected relation insert or keyed entity put hydrates its result from the write's own fetch, so one query does the whole call and no read-back follows it. If that answer names two relations, the call fails with provider_identity_cardinality_invalid (the write made two) instead of the read-back's provider_hydration_failed. - In Python packages generated with ordered collections (handler version 2), a generated model's single delete goes through the projected executor, as one query-plan/v3 delete plan, like its batch deletes. Packages generated without ordered collections keep the released delete path. An absent thing is still a successful no-op on both paths. - A projected batch write (Rust, Python and TypeScript batches in packages generated with ordered collections; every C batch) runs each stage as one statement over all its rows and splits only past the limits: contiguous, ordered chunks of at most 4,096 rows within the 32 MiB envelope less the plan bytes, fired on the same transaction, so a split batch stays all-or-nothing. Every binding and the proxy split a batch the same way. Before, a batch past those limits could not be sent; a single row too large for any chunk keeps the batch_statement_limit refusal. Batches in packages generated without ordered collections (Python, TypeScript, Rust) keep the released path and its limits. - Migration lease acquisition is one conditional write. A concurrent acquirer that commits between this acquirer's read and write now fails it with migration_execution_stale_fence instead of letting it silently take the newer fence. - Band 9 runs on the official Rust typedb-driver 3.13.6 (with typedb-protocol 3.13.4), up from 3.12.3. It serves TypeDB 3.12 and 3.13 servers (band 8 does not serve 3.13) and includes upstream's fetch-kind decoding fix. The release pin check now also fails when crates.io publishes a stable driver on a newer minor line. - TypeDB 3.13.6 is the recommended server, the V2 conformance baseline, and the default image in docker-compose.yml, docker-compose.proxy.yml, and test.sh. The installation guide lists the TypeDB window of every TypeBridge release and recommends the newest supported TypeDB. New workspaces and the shipped examples use the semantic profile typedb-3.13.6/v1; existing workspaces keep the profile they declare. The CLI --version output lists typedb-3.13.6/v1 among its semantic profiles. - The Python typedb-driver extra accepts >=3.11,<3.14, and >=3.12.3,<3.14 on CPython 3.14. CPython 3.14 remediation messages name the 3.13 driver line. - Answer-limit defaults are per transport. A direct session keeps the 2.2 values: 100,000 items, 64 MiB, 1,000,000 graph nodes, 4,000,000 attribute values, 1,000,000 collection members and role players, 30 seconds, and 3 statements. Proxy connections and the server use the wire limits, as in 2.2: 65,536 items, graph nodes, attribute values, collection members, and role players, and 32 MiB. One constructor chooses between them: QueryExecutionResourceLimits::default_for(AnswerTransport); Default is the direct policy. An answer between the two defaults is returned direct and refused through a proxy as a wire limit (limit items or bytes, source default). - C: a direct database, transaction, call, or batch without a limits descriptor now gets the direct defaults, looser than 2.2's 65,536 items; a proxy connection or remote context gets the proxy defaults. ABI 1.7 adds TYPE_BRIDGE_QUERY_DIRECT_DEFAULT_* and TYPE_BRIDGE_QUERY_PROXY_DEFAULT_*; the released TYPE_BRIDGE_QUERY_DEFAULT_* keep their 2.2 values. - Node: ProxyConnection.answerLimits reports the connection's ceiling, as Python's answer_limits does. - C database, read-transaction, and proxy executes run through the Rust query target that the other SDKs use, and the C remote context (the caller-owned exchange) prepares requests through the Rust proxy connection, so a connection's answer limits bind them the same way. The header no longer describes limit values as clamped: they are kept, and a value above its maximum is refused. - A generated package runs direct queries on the executor a proxy uses. Each request is adapted to a V2 plan under the package's embedded schema authority, so the same query is accepted or refused the same way direct and remote. The second selected-row executor is removed. - Generated manager all and first run as complete fetches on the same executor. Results and the manager_first_identity_not_unique refusal are unchanged. - A hydration graph and a row sequence in a reply are no longer capped at 65,536 by the container; the caller's budget bounds them. - selected_slots validation messages no longer spell the number sixteen; the ceiling is reported in the maximum detail. - Python's raw builders render TypeQL through the Rust core only. Raw Query/QueryBuilder, expressions, CRUD patterns, to_insert_query, and QueryCompiler.compile/compile_batch send every node (clause, pattern, statement, constraint, value, raw fetch string) to the core; the Python renderer and its silent fallback are gone, and a node the core cannot decode raises ValueError. Output is unchanged except: - a str literal with a non-string declared value type (LiteralValue("2024-01-01", "date")) renders unquoted in a pattern, statement, constraint, or value compiled on its own, as it already did inside a clause; - a small double whose Python form has a negative exponent renders positionally (0.00001, was 1e-05) where Python rendered it; - an integer outside the signed 64-bit range and a non-finite double have no TypeQL literal and raise ValueError (they were rendered as a quoted string or nan). - A generated Rust package verifies its embedded plan authority once per process instead of on every plan build (3.4 to 9 ms per plan before). A package that fails verification still fails every build.

Deprecated

Unless an entry says otherwise, each name below keeps working until it is removed in 3.0; the deprecated aliases build their replacement. 2.2 remote terminals were already awaited, so 2.2 remote-session code runs unchanged.

The released transaction entry points (Python Database.transaction(), TypeScript RustDatabase.transaction(), Rust ReadTransaction and WriteTransaction, the C ABI 1.6 functions) and the generated managers' write paths are not deprecated in 2.3: the staged transaction does not yet carry managers or typed queries.

  • TypeDB 3.11 support is deprecated in 2.3.0 and removed in 2.4.0. 2.3 still runs queries and CRUD on 3.11 servers; move to TypeDB 3.12 or 3.13 (3.13.6 recommended) before upgrading to 2.4.
  • Python update_with(func) on filtered queries and generated managers is deprecated since 2.3.0 for removal in 3.0 and emits a DeprecationWarning. It runs a host callback over rows it read; compute the new value with let_() in an update plan and stage it in a transaction instead (see the typed-queries guide).
  • Python type_bridge.session.Transaction, the direct-driver transaction wrapper, emits a DeprecationWarning; use Database.transaction().
  • Rust String schema-generation and fragment helpers (the ORM's schema::generator functions such as generate_define_block, attribute_definition and card_annotation) are deprecated since 2.3.0 for removal in 3.0. Use checked SchemaInfo::to_typeql or adapter builders. Python schema generation propagates checked errors as ValueError.
  • Legacy query nodes and String-returning compiler methods are deprecated since 2.3.0 for removal in 3.0: the ast types (Clause, Pattern, Statement, Constraint, Value, FetchItem, QueryNode, and their parts) and QueryCompiler::compile, compile_node, compile_clause, compile_pattern, compile_statement, compile_constraint and compile_value. Use generated typed query plans, or try_compile / try_compile_node, which return compiler::TqlError, when bridging legacy nodes. Python QueryCompiler.compile, compile_clause_body, compile_batch and parse_typeql_query emit DeprecationWarning; type-bridge's own helpers do not.
  • The frozen schema archive reader is deprecated since 2.3.0 for removal in 3.0: Python type_bridge_core._ArchivedTypeSchema.from_typeql emits a DeprecationWarning, and Rust type-bridge-core-lib _parser::parse_typeql and _schema::TypeSchema::from_typeql are #[deprecated]. Use Split-YAML schema authority.
  • Generated Python packages (each constructor emits a DeprecationWarning):
  • RemoteQuerySession(advertisement, exchange, limits, *, cancellation=None) is a QuerySession subclass that only builds QuerySession(ExchangeConnection(advertisement, exchange), resources=limits, cancellation=cancellation).
  • RemoteQueryLimits(max_items=..., max_bytes=..., max_collection_members=..., max_graph_nodes=..., max_attribute_values=..., max_role_players=..., deadline_ms=None) returns a QueryExecutionResourceLimits (items=, bytes=, ..., timeout_milliseconds=); isinstance(limits, RemoteQueryLimits) still holds, but read the new field names (limits.items, not limits.max_items).
  • RemoteQuery is Query; RemoteGroupedQuery is GroupedQuery.
  • Generated TypeScript packages (@deprecated in the declarations):
  • new RemoteQuerySession(advertisement, exchange, limits, cancellation?) is a QuerySession subclass that only builds new QuerySession(new ExchangeConnection(advertisement, exchange), { resources, cancellation }).
  • RemoteQueryLimits is the 2.2 shape { maxItems, maxBytes, maxCollectionMembers, maxGraphNodes, maxAttributeValues, maxRolePlayers, deadlineMs? } or a QueryExecutionResourceLimits; RemoteQuerySession converts the former. Use QueryExecutionResourceLimits.
  • RemoteQuery is Query, RemoteGroupedQuery is GroupedQuery, and RemoteQueryExchange is the ExchangeConnection exchange callback type.
  • Rust (#[deprecated]):
  • SchemaLoweringProfileFingerprint::compute(bytes) scopes the fingerprint to the TypeDB 3.12.1 lowering profile, as in 2.2. Use compute_for_profile(profile_id, bytes).
  • SchemaLoweringBinding::current(capabilities) binds the TypeDB 3.12.1 lowering profile, as in 2.2. Use SchemaLoweringBinding::for_semantic_profile or for_context, which select the registry of the profile in use.
  • RemoteDatabase<S> is ProxyDatabase<S>.
  • RemoteQueryTransport is the 2.2 trait; every implementation is a ProxyExchange. Implement ProxyExchange.
  • RemoteConnectionOptions::generated(limits, transport) returns ProxyConnectionPolicy::with_exchange(transport).answer_limits(limits), and RemoteConnectionOptions::new(scope, profile, limits, transport) adds .authority(scope, profile). RemoteConnectionOptions itself is only these constructors, because ProxyConnectionPolicy::new now takes a ProxyEndpoint; name ProxyConnectionPolicy in type positions.
  • RemoteQueryLimits::new(max_items, max_bytes, max_collection_members, max_graph_nodes, max_attribute_values, max_role_players) with .deadline_ms(ms) converts into QueryExecutionResourceLimits with the matching fields, the proxy default statements, and the proxy default timeout unless deadline_ms sets one. Use QueryExecutionResourceLimits.
  • DirectTls is TlsPolicy (type_bridge, type_bridge_orm, and type_bridge_orm::session).
  • MAX_QUERY_ITEMS, MAX_QUERY_BYTES, MAX_QUERY_GRAPH_NODES, MAX_QUERY_ATTRIBUTE_VALUES, MAX_QUERY_COLLECTION_MEMBERS, and MAX_QUERY_ROLE_PLAYERS (type_bridge and type_bridge_orm) equal the matching DEFAULT_PROXY_QUERY_*, their 2.2 values.
  • type_bridge_schema_migration_typedb::require_supported_migration_server still requires exactly TypeDB 3.12.3, the typedb-3.12.1/v1 server. Use require_supported_migration_server_for_profile.
  • type_bridge_orm::Transaction and type_bridge_orm::session::Transaction are OwnedTransaction; name OwnedTransaction. In 3.0 the staged transaction takes the session-level Transaction name.
  • DriverBackend::open_schema_fenced_read_transaction, the custom backend schema-fence hook; use the core transaction options.

Fixed

  • Generated entity models' insert_many (Python, Node) sends one batched insert again on TypeDB 3.12+, instead of one query per row (regression since 2.1.0).
  • Transaction::stage_plan refuses a query-plan/v3 program lifted from a V2 plan that keeps its filter or model terminal as compatibility evidence (query_plan_compatibility_unsupported), instead of running it without the filter and answering unfiltered rows.
  • Legacy query compilation no longer emits TypeQL that the TypeQL 3 parser rejects: attribute values render as one isa constraint instead of $a isa T; $a "v", keyed wildcards as fetch objects, zero-argument count as a reducer, and optional blocks parse back as try. Decimals keep exact digits and fetch keys are escaped.
  • Deprecated String compile and schema helpers return empty output for structured shapes the official AST rejects, instead of invalid TypeQL. Python QueryCompiler.compile and the server pipeline raise on non-Has relation attributes that earlier releases silently dropped.
  • Python compile_batch(..., "match") terminates each pattern with a semicolon, correcting batches rejected by TypeDB with TQL03.
  • Native schema migrations preserve ordered ownership and role list markers, including annotations, specialisations and removals, preventing scalar drift.
  • Backfill count queries retain unrelated negative filters and accept equivalent compact carried statements, correcting overstated matched/skipped totals.
  • Structured migration tuple functions emit comma-separated return types, correcting headers rejected with TQL03. Ordered role specialisations emit matching list markers on the parent, correcting invalid as clauses.
  • TOML long/int and bool aliases now emit TypeDB builtin integer and boolean domains instead of unresolved type labels (SYR4).
  • Schema generation omits unchanged inherited plays declarations on subtypes, correcting schemas rejected by TypeDB with SVL42. Introspection stores scoped role labels as local role names.
  • TOML structs now use TypeQL 3 struct name: field value type; syntax. Schema introspection binds type labels with label, correcting the obsolete type constraint in ownership and role queries.
  • Python and Node generated queries on a direct connection now run under the connection's answer limits (answer_limits / answerLimits given when connecting). They used only the session's own limits, so a session could return more, or run longer, than its connection allowed. Rust and C already applied the ceiling; every binding now shares one rule.
  • Generated manager filters in every binding now stop at the connection ceiling's timeout. They tightened resources to the ceiling but kept the deadline captured before it.
  • Repeated where clauses and chained and/or predicates build one flat conjunction or disjunction in every binding. A query with more than about thirty clauses used to nest past the canonical JSON depth of 64, so remote sessions refused it with canonical_json_too_deep and direct sessions ran it on a separate fallback path.

Security

  • Prebuilt distributions use rustls-webpki 0.103.16, which fixes RUSTSEC-2026-0382 (certificate verification could accept distrusted intermediates).
  • No distribution bundles the webpki root store any more (RUSTSEC-2026-0381, distrusted emSign intermediates in webpki-roots). The HTTP version probe and the proxy client already trusted only the operating-system roots or the configured PEM bundle; they now reach HTTPS through their own rustls connector instead of ureq's tls feature, which linked webpki-roots.

Tests and tooling

  • SDK conformance test contracts are named by concern: queries, models, administration, serialization and artifacts. The sdk-v1 smoke report is folded into queries, and administration runs natively on each TypeDB profile.
  • The writes SDK conformance suite runs its staged programs (the purchase, key constraints, and the shop checkout of examples/shop) in Python, TypeScript, Rust and C, directly and through the proxy, and checks that plan bytes, answers and stored state are identical, on TypeDB 3.13.6.
  • The SDK conformance sets (sdk-v1 to sdk-v6) run on TypeDB 3.12.3 and 3.13.6 through a per-profile matrix: each set lists the expected server and fingerprints for every supported semantic profile, and a report set must share one profile.
  • ./test.sh --typedb <line|all> runs the live tier on one supported TypeDB line (3.11.5, 3.12.3, or 3.13.6; default 3.13.6), or on every line followed by the two-server profile-upgrade run. Each line runs under its own semantic profile.
  • Generated live fixtures follow TYPE_BRIDGE_ACCEPTANCE_SEMANTIC_PROFILE (default typedb-3.13.6/v1) and require the exact server their profile names: 3.12.3 for typedb-3.12.1/v1, 3.13.6 for typedb-3.13.6/v1.
  • Perf tracking groundwork: the Perf workflow runs the core and ORM micro benchmarks on pushes to master, nightly, on dispatch and on pull requests, and uploads Criterion wall times and gungraun instruction counts as one validated perf-result/v1 file. Master, nightly and dispatch runs are stored on the perf-data branch, and the docs site charts that history at /perf/.
  • The same Perf run records the Python binding benchmarks in benchmarks/ (native query compilation, clause marshalling and validation through type_bridge_core) as binding.python.* metrics. The suite drops its pure-Python comparison benches and benchmarks/run_benchmarks.py with its TOML reports, and the benchmark pytest marker is gone: run uv run pytest benchmarks --benchmark-only.
  • The Perf workflow also records build times, artifact sizes and test-suite durations, and compares base and head on pull requests. On master, nightly and dispatch runs it times the Rust SDK pipelines (insert, fetch by key and filtered, update, delete, a 1,000-row batch, a staged purchase, migration apply) against TypeDB 3.13.6 and draws each pipeline's stage medians on /perf/.

[2.2.6] - 2026-10-16

Fixed

  • Commit failures report a definite abort only for TypeDB codes that prove the commit was rejected; other server failures now report unknown certainty, as transport failures already did, so callers no longer retry an unproven abort (#251).
  • Invalid given-row values report the column and type without exposing the value or parser details.
  • The local test harness validates every SDK report and comparison summary before logging SHA-256 evidence, and fails when validation fails.

[2.2.5] - 2026-10-14

Added

  • TypeDBClient::execute_classified preserves commit-failure certainty and driver text, distinguishing rejected commits from indeterminate outcomes while retaining the existing execute error contract (#251).

Fixed

  • Write queries ending in fetch now return commit failures instead of returning documents for writes that were never stored (#252).

Security

  • Updated quinn-proto to 0.11.19 for RUSTSEC-2026-0338 through RUSTSEC-2026-0342, addressing memory-exhaustion and connection-ID retirement issues in QUIC handling.
  • Updated rustls to 0.23.46 for RUSTSEC-2026-0346 through RUSTSEC-2026-0349, addressing TLS secrets in Debug output, a key exchange downgrade, certificate decompression memory use and data sent after ECH rejection.

[2.2.4] - 2026-10-08

Fixed

  • Closing a transaction after a bounded query stops early no longer wedges the TypeDB server. Bounded queries asked the server to stream one answer per batch; with that prefetch, TypeDB 3.11 to 3.13 could deadlock while closing the paused stream whenever the driver's latency estimate rounded to 0 ms. The close then never completed, the transaction never timed out, and its database stayed "in use" until the server restarted. Bounded queries now request two answers per batch, which leaves room for the stream's trailing messages.
  • Python batches running on several threads no longer leave the garbage collector disabled. Each batch disabled the collector and restored the state it had seen on entry, so batches ending out of order could turn collection back on mid-batch or leave it off for the rest of the process. The collector is now restored only when the last running batch ends.

[2.2.3] - 2026-10-07

Security

  • Install Debian's fixed Bookworm PCRE2 (10.42-1+deb12u2) and Perl (perl-base 5.36.0-7+deb12u4) packages in the server image for both architectures, pinned by checksum. The pinned base image predates fixes for CVE-2026-103111, CVE-2026-13221, CVE-2026-42496, CVE-2026-8376, CVE-2026-42497, CVE-2026-48962, CVE-2026-57432, and CVE-2026-57433.

Fixed

  • Bounded projections sorted by a unique key now validate when they select mandatory single-valued fields, such as a [1,1] Double. The window-order proof derives each [1,1] attribute from its determined owner, and each player of a [1,1] role from its determined relation; a key it cannot use on its own, such as a Double, may sort alongside the keys that determine it. Optional, negated, and disjunctive patterns do not propagate, and a Double alone is still refused with query_plan_window_order_not_total. Plans that validated before keep their canonical bytes (#244).

[2.2.2] - 2026-09-14

Security

  • Require rustls 0.23.45 and update resolved TLS dependencies to fix RUSTSEC-2026-0285, which rejects TLS 1.3 handshake messages crossing encryption levels.

Fixed

  • Avoid unused imports and empty function/struct re-exports in generated Rust for schemas containing attributes and entities without roles, functions, or structs. Pristine consumer test modules pass strict Clippy.

[2.2.1] - 2026-09-14

Fixed

  • Add per-binding canonical type-name overrides through workspace type-names and Rust ProjectionConfig. Resolve generated model/reference collisions without changing database labels or semantic schema identity.
  • Generate Rust validation checks on separate lines and emit Clippy-clean reference validation and collection encoding. Cover pristine generated consumer test modules under -D warnings.

[2.2.0] - 2026-09-14

Fixed

  • Apply Debian's PCRE2 security update to both server-container architectures, fixing CVE-2026-86145 and CVE-2026-89161 with checksum-pinned packages.
  • Fix generated TypeScript construction for unbounded roles and list fields by recognizing canonical "unbounded" cardinality metadata.
  • Project model fields and roles that collide with runtime members to names with a trailing underscore, including the physical string key name as name_. Preserve schema identity and existing non-colliding names. Regenerate complete TypeScript packages after updating the generator and compatible runtime.

C SDK and standalone CLI

  • Release the standalone CLI and ABI 1.6 C shared runtime for Linux x86_64 on Ubuntu 24.04, with independent generated schema packages and complete V1โ€“V6 application acceptance. Signed public artifacts passed independent provenance, installation, C17/C++17, and live-consumer checks.
  • Add exact-source artifact verification and signed promotion to the GitHub release draft, preserving accepted archive bytes and supporting only absent-or-identical partial-upload recovery.
  • Use TypeDB 3.12.3 for the exact connected migration baseline while retaining the canonical typedb-3.12.1/v1 semantic profile.

[2.1.0] - 2026-09-08

Security and release reliability

  • Forward-ported the patched PyO3 0.29.2 and dependency graph from the 2.0.2 maintenance release, preserving the generated-only 2.1 boundary, abi3-py312 and GIL-required semantics. CI and releases require fresh dependency audits.
  • Pinned deterministic native license selection and the metadata-2.5-compatible PyPI publisher; validate facade metadata before cross-registry publication.

Changed

  • Generated-only application bindings (#189) - Split YAML plus type-bridge schema generate is now the sole active schema/model authoring path. Generated Python, TypeScript/Node, and Rust packages retain the supported CRUD, transaction, hook, query, reducer, local/remote, hydration, and diagnostic outcomes previously exercised through handwritten models. Python keeps the concise generated single-type manager API, including Person.manager(db).put(...) and lookup-suffixed filter(...) terminals.
  • TypeDB 3.11/3.12 support window - Native packages now contain only bands 8 and 9. Active TypeDB 3.8/3.10 support, provider sources, warning APIs, build features, matrices, and release inputs are removed; retired versions fail before data work.
  • Authoring cutover with recovery retained - Handwritten Python/Node/Rust schema declarations, direct TOML generator routing, programmatic TypeQL model generation, and root Python/JSON migration authoring are removed. Read-only TOML conversion and archived migration loading, checksum verification, ledger import, snapshots, adoption, and recovery remain.
  • 2.1.0 artifact identity - Python, npm, Cargo, generated Rust templates, documentation, and release validation share the 2.1.0 identity. See the 2.1.0 release notes for the complete cutover inventory and upgrade guidance.

[2.0.2] - 2026-09-07

Security and compatibility notice

  • Patched PyO3, crossbeam-epoch, h2, rustls-webpki, anyhow, rand and chacha20 while retaining 2.0.x APIs, provider support, existing warnings and abi3-py312.
  • Published the expanded, fully qualified 2.1 removal/replacement inventory and safe <2.1 pins in the 2.0.2 release notice. This new notice does not rewrite the historical 2.0.0/2.0.1 commitments.
  • Recovered the unchanged Python facade artifacts with a metadata-compatible publisher; the release notice records original source and recovery-control provenance. Existing tag and registry bytes were not replaced or rebuilt.

[2.0.1] - 2026-08-03

New Features

  • Cargo-distributed Rust SDK - type-bridge and its complete supporting Rust graph are publishable to crates.io in dependency order. Release gates package and preflight every candidate without mutation, preserve the checksum-pinned historical TypeDB band-7 crates, and publish the authorized band-8 compatibility packages only from the accepted stable tag. Python and Node native binding crates retain their separate PyPI and npm identities.

Documentation

  • Added a linked crates.io version badge and crates.io-first Rust installation guidance while retaining the exact Git instructions for historical 2.0.0.

[2.0.0] - 2026-07-31

New Features

  • Canonical Split-YAML schema and multi-language projections (#188) - TypeBridge V2 workspaces now make versioned typebridge.schema-set/v1 manifests and typebridge.schema/v2 fragments the canonical schema authority. The strict, bounded YAML subset rejects unknown or duplicate facts, unsupported future shapes, unsafe paths, and nondeterministic discovery before provider I/O. Rust resolves the complete document set once and projects the same declared meaning into Python, TypeScript/Node, and Rust bindings. The workspace CLI validates schemas offline with schema check, generates every configured SDK with schema generate, and emits the deterministic authority consumed by V2 executors with schema export-declared.
  • Offline history-based migrations and workspace CLI (#188) - Rust now authors immutable migrations/v2 programs from the desired schema and committed history, orders and verifies the chain, detects drift, and never infers destructive approval. The type-bridge migration CLI exposes make, plan, apply, verify, and adopt against named workspace environments. Legacy adoption validates the complete dependency graph, applied ledger, original checksums, portable sidecars, and snapshot authority; it records a writer cutover and canonical adopted-genesis.typeql without re-executing legacy operations such as RunPython. Failed adoption remains retryable, while retained legacy readers and historical artifacts stay available.
  • Authenticated local/remote Query V2 and standalone executor (#188) - the same Rust-owned canonical plan, invocation, schema/profile validation, capability checks, limits, and structured diagnostics now govern direct execution and the standalone server's /v2/capabilities and /v2/query routes. Prepared remote requests bind the executor identity, nonce, fingerprint, expiry, capability set, and response budget before provider transaction construction; signed successes and failures are authenticated before hydration. The capability advertisement is an explicit trust input that callers obtain over authenticated TLS or pin out of band. One awaited remote terminal performs exactly one caller-owned exchange with no built-in discovery, credential, HTTP-client, retry, traversal, or follow-up hydration behavior.
  • Complete V2 query authoring and remote model facade (#195) - Python now exposes the complete low-level Rust plan builder from type_bridge.query_v2, with the equivalent Node API at @type-bridge/node/query-v2. Opaque handles cover the full V2 pattern, function, reduction, stage, document, reachability, typed-input, and invocation vocabulary while Rust alone owns validation, canonical bytes, fingerprints, and capabilities. The model-oriented RemoteQuerySession / RemoteQuery facade reuses the released immutable direct grammar with explicitly awaitable terminals: composition performs no I/O, and one awaited terminal performs exactly one caller-owned exchange with no built-in discovery, authentication, HTTP client, retry, traversal, or hydration query. Authenticated graph validation and caller ceilings precede model construction; direct and remote paths preserve result order, structured diagnostics, and registered concrete-subtype hydration. V1 query facades remain operational with no removal schedule. The Rust-owned count/max/mean/median/min/std/sum reducer vocabulary is pinned through Python and TypeScript source and packaged declarations. The Python and Node V2 binding smokes now author plans at runtime, and exact-artifact parity covers documents, bounded reachability, and authenticated structured failures; canonical, fingerprint, hostile, V1 wire, MatchRequest, and released compatibility fixtures remain retained.
  • Bounded typed reachability (#193) - Python and Node typed query sessions can now express an inclusive finite directed walk over an exact relation and ordered endpoint roles. Zero depth is concept identity; positive depths admit cycles and repeated vertices while proof paths remain existential, so selected result identity and stable ordering retain the ordinary typed-query contract. Bounds and expansion budgets fail during construction before provider I/O, and Rust lowers the full range into one query without client-side traversal.
  • Public generated Rust application client - type-bridge and generated schema crates now expose owner-branded entity/relation CRUD, exact and subtype reads, complete replacement, reusable write/read transactions, typed expressions and reductions, selected/collected pages, bounded reachability, and identical local/one-exchange remote materialization. The generated crate has only one direct TypeBridge dependency and the complete consumer contract is accepted on Rust 1.88. Public ErrorCategory, stable codes, structured paths, and validation phases now survive both direct and remote adapters; caller-owned transports use Error::remote for classified transport failures.
  • Hardened server OCI distribution - ghcr.io/ds1sqe/type-bridge-server:2.0.0 is built once for linux/amd64 and linux/arm64 from digest-pinned bases with the locked V2-capable server. Exact layouts run as UID/GID 10001 with a read-only root, no capabilities, and no-new-privileges; acceptance covers V1 compatibility, authenticated V2, and the external generated Rust application. Stable publication imports the accepted manifests without rebuilding, verifies all aliases and digests, and attaches keyless signatures, SPDX SBOMs, provenance, and scan evidence.

Changed

  • Fail-fast schema-annotation compatibility - all ORM schema-query boundaries now reject @doc/@meta before provider dispatch when the known TypeDB server is older than 3.12. One-shot execution rejects before opening a transaction, while caller-owned schema transactions reject before their provider query. The 3.12 generated-projection fixture remains annotation preserving and runs only in the 3.12 TLS lane; older lanes continue to prove transport compatibility.
  • Legacy TypeDB server notices (#189) - each successful TypeDB 3.8/3.10 connection now emits one filterable compatibility notice while continuing normally: Python uses TypeDBServerDeprecationWarning, Node uses standard warning type DeprecationWarning, and Rust tracing uses code TYPE_BRIDGE_TYPEDB_LEGACY_SERVER. The conservative unknown-version notice is limited to an actually negotiated band-7 fallback and does not claim an exact server version; missing HTTP identity on band 8 or 9 does not warn. TypeDB 3.11 and 3.12 connections do not emit it. Active 3.8/3.10 support remains operational throughout every 2.0.x release and is removed in the 2.1.0 minor. Warning lookup or delivery cannot turn a successful connection into a failure: Python warning-to-error promotion and synchronously throwing replacements of Node's process.emitWarning are contained, while Node --throw-deprecation suppresses this compatibility notice. Exceptions raised later by application-owned Node warning listeners retain ordinary Node process semantics. The removal schedule names a single release, documented exactly in V2 Deprecations. Every scheduled removal lands in the 2.1.0 minor release as a deliberate, exactly-enumerated exception to ordinary major-version scheduling: active TypeDB 3.8/3.10 provider and driver support ends (the wheel then embeds only the band-8 and band-9 driver lines), and direct schema.toml desired-schema authoring, generate_models(..., format="toml"), and Python .toml generator auto-routing are removed; both TOML authoring routes emit a filterable Python DeprecationWarning. Deployments retaining a 2.1.0-scheduled surface pin type-bridge>=2,<2.1. V1 query facades have no removal schedule, and archival migration readers, checksum verification, ledger import, snapshots, converters, and the legacy-frontier bridge remain retained. The 2.1.0 removal inventory further includes:

  • type_bridge_core.TypeSchema, type_bridge_core_lib::schema::TypeSchema, type_bridge.SchemaInfo, type_bridge.migration.SchemaInfo, type_bridge_orm::SchemaInfo, type_bridge.SchemaManager, type_bridge.migration.SchemaManager, and type_bridge_orm::SchemaManager;

  • the fused type_bridge.Role[T] / type_bridge.models.Role[T] declaration surface; and
  • authoring new legacy root NNNN_*.py migrations and sibling JSON files, plus treating those files as active migration authority.

type_bridge.MigrationManager / type_bridge.migration.SimpleMigrationManager; the Python V1 type_bridge.Query and type_bridge.QueryBuilder; the Node V1 TypedQuery<T, Row> and TypedGroupByQuery<Row>; and the Rust V1 type_bridge_orm::MatchRequest entity, relation, and group-by query facades are each deprecated without a removal schedule. Read-only TOML conversion, legacy migration readers, original checksums, applied-ledger import, snapshots, historical server metadata, and the legacy-frontier bridge are explicitly retained. Apart from the named 2.1.0 removals there is no other removal or calendar cutoff โ€” there is no 3.0.0 removal plan; deployments retaining any scheduled surface can pin type-bridge>=2,<2.1. - Rust V2 source/Git distribution boundary - the internal V2 semantic, migration, projection, workspace, and CLI crates remain first-party workspace packages with publish = false; they are not crates.io release identities. The public type-bridge package still depends on that unpublished graph, so 2.0 distributes it from the exact release Git revision instead of publishing a broken crates.io package. The release gate blocks Cargo mutation and names the exact source/Git SDK in the closed artifact set. - Direct Python driver 3.12.1 - CPython 3.14 dependency markers, native artifact probes, and live compatibility cells now use the current 3.12.1 Python driver patch; CPython 3.12โ€“3.13 retains the released multi-line compatibility contract. - Upstream-native TypeDB 3.12 runtime - the default band-9 path now uses the official upstream Rust driver/protocol packages directly and is exercised against the TypeDB 3.12.1 conformance server. The exact source pin is the newest non-yanked stable 3.12.x release at the first-publish cutoff (currently 3.12.1); retries after that cutoff retain the exact release graph already started. No active, consumed, or release-input TypeBridge band-9 fork exists. - Terminal embedded-driver close dispatch (#196) - Python, Node, and Rust database close boundaries now invoke the selected driver's upstream idempotent force_close() API and immediately reject new work. Upstream 3.12.1 dispatches shutdown but releases its final callback worker only when the last shared driver lease drops, so TypeBridge does not promise a synchronous worker join from a retained closed handle. This is a temporary downstream lifecycle workaround, not a driver or protocol patch; #196 is its removal gate. - Legacy multi-band compatibility packaging - band 7 reuses the already published type-bridge-typedb-driver-b7 3.8.1 and protocol 3.7.0 packages; band 8 uses namespaced driver 3.11.5 and protocol 3.11.0 source-unmodified packaging candidates. The later Cargo-distribution authorization permits first publication; these exact source-unmodified packages remain the authorized compatibility artifacts, with protocol preceding driver. Their Rust source behavior is byte-identical to the respective upstream archives, with no downstream transaction-close or other behavioral patch. Namespacing is solely a Cargo package-identity mechanism that permits all protocol bands in one native graph. TypeDB remains the original upstream owner, and its Apache-2.0/MPL-2.0 licenses are preserved.

Documentation

  • Multi-surface documentation and contributor workflow (#200) - the public README and MkDocs site now present TypeBridge as one Rust semantic engine exposed through Python, TypeScript/Node, generated Rust, schema and migration tooling, immutable queries, and the standalone server. The README is kept below 200 lines with a runnable schema-before-CRUD quick start and an accessible repository-owned hero that renders on package pages. Stable detailed URLs now sit behind focused SDK, modeling, data, schema, operations, Python API, and maintainer routes. DEVELOPMENT.md is the canonical contributor guide, with regular cross-platform AGENTS.md and CLAUDE.md pointers; stale test totals and directory snapshots are removed, and docs/SKILL.md now validates and routes workflows across every supported product surface.

[1.5.11] - 2026-07-19

Bug Fixes

  • Declared role-player migration authoring (#190) - Migration authoring now reduces inheritance-flattened role-player vectors to the capabilities actually declared in each schema. This prevents phantom plays operations, preserves declaration changes hidden behind identical effective player sets, and orders player changes safely around entity and relation hierarchy updates.

[1.5.10] - 2026-07-16

Bug Fixes

  • Sub-type migration planning and apply (#190) - Planning a migration that adds an entity or relation with a parent no longer panics with no entry found for key. Authored add operations now emit parents before children and carry only declared capabilities, so the child's define step keeps its sub clause without redeclaring inherited attributes or roles, which TypeDB rejects at apply time. Verified against live TypeDB servers from 3.8.3 through 3.12.1.

[1.5.9] - 2026-07-15

New Features

  • Public migration and TOML-transpiler crates - type-bridge-migration and type-bridge-toml-transpiler now participate in the validated crates.io publication graph. The transpiler publishes as an independent crate; migration publishes only after its type-bridge-orm dependency is visible in the registry index.

Bug Fixes

  • Fail-closed Python relation players (#170) - Python typed queries reject nested relation-player materialization during planning, before provider I/O, while preserving legacy Role[Relation] declarations and CRUD. Defensive result hydration also rejects unsupported evidence; Node retains its released shallow V1 result contract.

Testing & Tooling

  • Exact F8 release-artifact gate (#170) - registry publication now waits for the exact Python wheels and packed Node tarball to prove the Python rejection and Node shallow-result contracts live on TypeDB 3.8.3, 3.11.5, and 3.12.1.

[1.5.8] - 2026-07-15

New Features

  • @doc/@meta schema annotations (#169) - TypeDB 3.12's schema documentation and metadata annotations are declarable from all three model surfaces: TypeFlags(doc=..., meta=...) / AttributeFlags(doc=..., meta=...) and the Flag(Doc(...), Meta(...)) ownership markers in Python, with matching TypeScript typed-layer and Rust static-model options, plus role-level doc=/meta= on Role(...). Annotations are emitted in schema define lowering, round-trip through the generator with three-target surface parity, and are carried by schema export/introspection.

  • Annotation-aware migrations (#169) - makemigrations detects @doc/@meta additions, value changes, and removals on types, ownerships, and roles, authoring new ModifyTypeAnnotations / ModifyRoleAnnotations operations with reverse steps. Annotation transitions lower to per-annotation schema steps (grouped define/undefine blocks, one redefine per value change; removals first) โ€” this also fixes ModifyOwnership transitions involving parameterless annotations (@key/@unique), which the old blanket-redefine lowering rejected live (REX28). Annotation-only changes classify as metadata-safe.

  • Version gate for schema annotations (#169) - the server version detected by the connect-time gate is retained and exposed as Database.detected_server_version(). Schema-apply seams (SchemaManager.sync_schema, the migration executor) check annotated DDL against it before sending: annotated schemas bound for a pre-3.12 server fail client-side with an actionable versioned error instead of a server syntax error. Database.check_schema_annotation_support() exposes the check directly.

  • Band-9 embedded driver (#169) - the TypeDB 3.12 Rust driver ships vendored as type-bridge-typedb-driver-b9 alongside the band-7 fork and the crates.io band-8 driver, so 3.12 connections negotiate the native band-9 protocol automatically. Live measurement surfaced a hazard: a band-9 connection attempt crashes a 3.11 server, so the gRPC fallback discovers unknown servers through band 8 and upgrades to band 9 only after the reported version proves it safe.

  • given-stage parameterized queries (#169) - one compiled TypeQL pipeline runs over many input rows, with the rows passed through the driver API instead of interpolated into the query string. Database.execute_with_rows() / TransactionContext.execute_with_rows() expose the raw surface (requiring both TypeDB 3.12+ and the negotiated band-9 provider; Database.supports_given_stage() reports that effective capability), and entity insert_many() automatically rides one given pipeline for homogeneous batches when available โ€” measured ~4x faster than the per-row path at 1000 rows โ€” while degrading transparently to per-row inserts on older servers, band-8 fallbacks, and heterogeneous batches.

  • Unified immutable typed queries (#170โ€“#177) - added additive type_bridge.typed and @type-bridge/node/typed facades with owner-aware variables, fields, and roles; exact or subtype matching; exact 1โ€“16-slot positional and named output typing; collected pages; and distinct-root page/count/exists operations. Rust owns canonical validation, TypeQL lowering, bounded execution, result identity, and transaction lifecycle. On negotiated band-9 connections, supported predicate values travel separately from TypeQL in one compiler-owned given row; older bands retain the validated inline path, and both routes preserve bounded streaming; existing package-root query and manager APIs remain available unchanged.

  • TypeDB 3.12 server support - the compatibility window now extends to 3.12.x. Compatibility was measured live: server 3.12 accepts band-8 (3.11) drivers, while a 3.12 driver is refused by a 3.11 server, so the version gate now models servers as accepting a set of protocol bands and negotiates the connect band from that set. The embedded band-9 driver is selected only after a server is confirmed as 3.12; unknown-server fallback starts with band 8 to avoid probing a 3.11 server with the incompatible band-9 client. Installed Python driver 3.12 (band 9) is dispatched with the band-8 option form and gated correctly against both 3.11 (reject) and 3.12 (accept) servers; the typedb-driver extra now allows <3.13.

Bug Fixes

  • Reliable band-7 fallback on remapped TypeDB endpoints - when the HTTP version probe is unavailable, a lazy band-8 connection failure now advances to band 7 instead of terminating negotiation early. Rust integration helpers and Node parity consumers also honor the configured HTTP port.
  • CPython 3.14 direct-driver compatibility - optional and development dependencies now select TypeDB driver 3.12.0 on CPython 3.14, with native constructor coverage. The CPython 3.12โ€“3.13 development environments retain driver 3.11.5 for the default 3.11 server, while the public extra continues to permit driver lines 3.8โ€“3.12. The embedded ORM runtime remains compatible with TypeDB 3.8โ€“3.12 on every supported interpreter.
  • CPython 3.12 typed-facade compatibility - package metadata, defaulted owner generics, static-tool targets, CI, and exact-artifact acceptance again cover the declared >=3.12,<3.15 release range.

Testing & Tooling

  • Typed-query artifact and live parity gates (#170โ€“#177) - added isolated Python-wheel and packed-npm consumers, positive/negative static contracts, native resource/lifecycle/snapshot regressions, and shared Python/Node live query coverage on the TypeDB 3.8, 3.10, 3.11, and 3.12 server lines.
  • Release-candidate acceptance (#170โ€“#177) - each package registry consumes only its accepted immutable candidate; crates.io publication additionally waits for both complete Python archive/metadata/payload validation and exact npm-package acceptance. Exact-wheel runtime and typing consumers run on CPython 3.12, 3.13, and 3.14, and exact npm-package runtime consumers run on the declared Node 18 and 20 lines. Registry retries accept an existing artifact only when its published hash matches the candidate.
  • TypeDB 3.12.0 CI legs - all ordinary Python integration groups (including session coverage for given negotiation), node-integration, and cross-language-parity matrices gained typedb/typedb:3.12.0 legs (paired with Python driver 3.12.0), and the version-gate cells gained a NEG-driver-band9 regression for the asymmetric 3.12-driver / 3.11-server rejection.

[1.5.6] - 2026-07-10

New Features

  • Expose migration-state schema boundary for external ledgers (#165) - added a public migration-state schema descriptor and filtering helpers so callers can keep migration execution metadata in an external state store while leaving target application schema management untouched.

  • Pluggable migration state manager (#165) - MigrationExecutor now accepts an optional state_manager so external orchestrators can inject their own state persistence backend while retaining the existing default TypeDB-backed behavior.

Testing & Tooling

  • Integration coverage for external-state migrations (#165) - added live tests for external ledger execution paths and schema filtering behavior that validate default and injected-state modes across TypeDB live integration.

[1.5.5] - 2026-06-30

Bug Fixes

  • Strict Boolean wrappers - Boolean now rejects non-bool values at construction, Pydantic validation, Pydantic serialization, hydration, and Rust-backend dynamic value boundaries instead of truthiness-coercing strings such as "False" into True.

Testing & Tooling

  • Boolean strictness regressions - added unit coverage for direct Boolean construction, Pydantic hooks, CRUD hydration through wrap_attribute_value, and Rust backend boolean value marshalling.

[1.5.4] - 2026-06-26

New Features

  • Generator name-case overrides (#163) - bindgen now accepts case annotations case-insensitively, including @case(PascalCase) and language-scoped forms such as @case(Python, SnakeCase).
  • PascalCase and TOML bindgen metadata (#163) - Python model generation now maps PascalCase TypeDB names to TypeNameCase.CLASS_NAME, and TOML schemas can carry bindgen_case plus annotations metadata for generated bindings.

Bug Fixes

  • Mixed-case generated names (#163) - class-name generation now preserves mixed-case sub-segments such as FirstPerson instead of lowercasing them during Python and Rust bindgen output.
  • Explicit generated type names (#163) - generated attribute configs now emit explicit name="..." flags when the TypeDB name does not align with the default language-specific name inference.

Testing & Tooling

  • Cargo CI isolation (#163) - CI now keeps Cargo homes and caches outside the workspace, isolates cache keys by lockfile, and pins the stable Rust toolchain to reduce release-run cache and registry churn.
  • Cargo lock checksum repair (#163) - refreshed the affected Rust lockfile checksums so locked metadata validation passes cleanly in release checks.

[1.5.3] - 2026-06-24

New Features

  • ORM-backed Python data migrations (#158) - migrations can now use ops.RunPython(...) to run normal TypeBridge ORM code during migration execution, including User.manager(db).filter(...), bulk inserts, updates, deletes, and JSON/TOML-backed data loading.
  • Database-backed migration history (#158) - applied migration state and execution attempts are stored in TypeDB through type_bridge_migration and type_bridge_migration_run, including run IDs, checksums, direction, status, timestamps, errors, and executor metadata when available.
  • Historical snapshot bindings for generated migrations (#160) - generated migrations now import stable time-state bindings such as migrations.snapshots.v0001.User instead of the active generated model package, keeping old migrations replayable after later bindgen output removes or reshapes types.

Changes

  • Snapshot drift protection (#160) - existing snapshot packages are validated by schema hash, generated file hash manifest, and top-level binding exports before reuse, so stale or hand-edited historical bindings fail clearly instead of silently changing migration semantics.

Documentation

  • Migration guide added (#158/#160) - added a dedicated migration guide that explains the generated migration workflow, why snapshots matter, RunPython data migrations, rollback, sidecar checksum drift, and TypeDB-backed migration/run history.

[1.5.2] - 2026-06-18

New Features

  • Rust bindgen model renderer (#157) - Python, TypeScript, and Rust model rendering now run through the shared Rust bindgen engine, with Python generate_models and the Node generator facade delegating to native render_models_json bindings.
  • Renderer deduplication (#157) - The old Python Jinja renderer and duplicated TypeScript renderer implementation were removed, so future model generation changes land in one core implementation with cross-language parity coverage.

Bug Fixes

  • Shared TypeDB runtime parity (#155/#154) - type_bridge_server::typedb::TypeDBClient now uses the same gRPC-only connect path, HTTP-probe fallback, and exact server_version override logic as the ORM Database.connect surface. The ORM and server both depend on a shared TypeDB runtime crate for driver construction, database lifecycle, transaction execution, and JSON result conversion.
  • Node gRPC-only connect option parity (#154) - @type-bridge/node ensureDatabase and RustDatabase.connect now accept serverVersion, letting Node callers skip the HTTP version probe for gRPC-only deployments while still validating the exact TypeDB server version.

[1.5.1] - 2026-06-17

Bug Fixes

  • gRPC-only TypeDB connect support (#154) - Database.connect(..., server_version=...) now accepts an exact server version across Rust, PyO3, and Python connect surfaces, letting deployments without a reachable HTTP version endpoint skip the HTTP probe while still validating the supported window.
  • HTTP probe fallback to embedded driver negotiation (#154) - when no server_version is supplied and the HTTP probe fails, the Rust runtime now falls back through gRPC band negotiation, trying band 8 and then band 7 and reporting every attempted path if neither driver can connect.
  • Version-gate CI coverage for fallback paths (#154) - CI now includes positive cells that force the HTTP probe onto a bad port and assert the gRPC fallback succeeds, with helper updates for both success and rejection expectations.

New Features

  • Band-aware server database admin API (#155) - type_bridge_server::typedb::TypeDBClient now exposes database_exists, create_database, delete_database, and reset_database, dispatching through the embedded TypeDB driver band selected at connection time.
  • Node database lifecycle parity (#155) - @type-bridge/node RustDatabase now exposes databaseExists, createDatabase, deleteDatabase, and resetDatabase on the bound database handle, matching the Python/Rust ORM lifecycle surface.

[1.5.0] - 2026-06-15

Changes

Rust-SSOT typed migrations from generated schema diffs (#152)

  • Generated migrations default to typed operations โ€” makemigrations now renders schema diffs as operations such as ops.AddAttribute(...), ops.AddEntity(...), ops.AddRelation(...), ops.AddOwnership(..., optional=True), and role/player changes instead of flattening schema diffs to raw TypeQL.
  • Rust remains the migration execution source of truth โ€” generated migration sidecars preserve structured Rust OperationSpec values, and the Rust planner lowers typed operations to executable TypeQL at planning/execution time.
  • ops.RunTypeQL remains supported as an escape hatch โ€” handwritten data migrations and custom TypeQL can still use ops.RunTypeQL(...); Rust planning infers schema vs write transaction kind so data scripts execute correctly.
  • Django-style schema.toml lifecycle documented โ€” the generator guide and examples/advanced/toml_migration/ now show the user flow: edit schema.toml, run bindgen/generator and makemigrations, receive 0001_initial.py, migrate, edit the TOML again, and receive a follow-up typed migration such as 0002_add_email.py.
  • Real smoke coverage added โ€” integration coverage exercises TOML bindgen, an initial typed migration, real data insertion, a typed optional-ownership delta, an explicit ops.RunTypeQL data migration, and a failing migration path that remains unapplied while preserving prior data.

Rust runtime as the default Python execution backend

  • Database.connect() now opens the embedded Rust runtime by default โ€” the Python ORM no longer needs the optional external typedb-driver package for normal connection, schema, CRUD, query, migration, or database lifecycle operations.
  • Database lifecycle operations are Rust-backed โ€” database_exists(), create_database(), delete_database(), and schema export use the same embedded Rust runtime path as query execution.
  • Direct Python driver access remains explicit โ€” Database.driver still opens the optional external Python typedb-driver and keeps its installed driver/server compatibility gate for callers that need direct driver APIs.

Dual-band TypeDB driver support: servers 3.8โ€“3.11 served by one artifact (#145)

  • Both TypeDB Rust driver lines now embedded โ€” the wheel ships a vendored band-7 fork (3.8.1) alongside the upstream band-8 driver (3.11.5). The runtime dispatches to the correct driver at Database.connect() time based on the server's protocol band; no user-side configuration is required.
  • TypeDB 3.11 newly supported โ€” band-8 (3.11.x) servers are now served in addition to the existing band-7 window.
  • Existing 3.8/3.10 deployments keep working without change โ€” the band-7 embedded driver is a drop-in for the previous release line; upgrading type-bridge does not require a server upgrade.
  • One release artifact covers TypeDB 3.8.0 through 3.11.x โ€” the per-band install guidance is retired. Install type-bridge and connect to any server in the supported window.
  • CI proven on all three server lines โ€” test-integration, node-integration, and cross-language-parity now fan across 3.8.3, 3.10.4, and 3.11.5 (parity ร—2). The version-gate-cells job retains only the true rejection cells (NEG-window, NEG-driver).

Cross-language CI and release coverage (#110)

  • Node binding built, tested, and released โ€” the @type-bridge/node binding is now built and gated in CI (native module, TypeScript surface, unit, .d.ts baseline, and package smoke), runnable locally via scripts/check.sh node, and packaged as a tarball attached to each GitHub release (registry publish staged behind an NPM_TOKEN).
  • Cross-language parity enforced โ€” the Python/Node parity suite runs against live TypeDB in CI under a strict mode that fails (rather than silently skips) when the binding is unbuilt, so a semantic divergence between the two bindings reds CI; the migration integration group is also covered.
  • Release hardening โ€” third-party GitHub Actions are pinned to commit SHAs, and a crates.io publish that fails for any reason other than an already-published version now fails the release instead of being swallowed.
  • Node binding integration gated in CI โ€” a node-integration job runs the binding's own live-TypeDB suites (test:integration, which chains test:typed-integration) against a TypeDB service, mirroring the Python integration job. Previously only the offline Node gates and the Python-side parity suite ran; the binding's own integration assertions now red CI on a regression.
  • Consolidated test/check scripts โ€” test.sh is now the single full-test entrypoint (Rust + Python + Node, unit + integration) with --no-integration, --proxy, and --no-isolated flags; it manages a TypeDB by default. The test-integration.sh, test-integration-dind.sh, and test-proxy-integration.sh scripts (and the Docker-in-Docker image stack) are retired into those flags, and scripts/check.sh is the single canonical check (the redundant root check.sh is removed).

Generator parsing routed through the Rust core (#125)

  • lark removed โ€” the generator no longer depends on lark. TQL schema parsing runs entirely through the Rust type_bridge_core core, which is the single source of the parsed schema. The typeql.lark grammar and the lark-vs-Rust differential test have been deleted, and lark is dropped from the runtime dependencies.
  • Structured function return types โ€” FunctionSpec.return_type is now a structured ReturnTypeSpec (a is_stream flag plus an ordered list of ReturnTypeItem(name, optional)) instead of a formatted string. Optionality is carried as a boolean, so the intermediate representation is language-neutral and additive for future bindings. Generated output is unchanged โ€” the renderer reconstructs any ? tokens at its own emit site.

New Features

Plays-side role cardinality (#130)

  • Cross-language plays-cardinality authoring โ€” Rust SchemaInfo, Python Role(..., plays_cardinality=Card(...)), TypeScript role(..., { playsCardinality: Card(...) }), and TOML plays = [{ card = "..." }] now emit plays relation:role @card(...) through the shared Rust schema emitter/parser path.
  • Relates/plays separation โ€” relates-side cardinality still constrains players per relation instance, while plays-side cardinality constrains how many relation instances a single player may participate in for that role. The two constraints may coexist on the same role.
  • Generated surface round-trip โ€” parsed TypeQL with plays-side @card renders back to Python and TypeScript role declarations, preserving authoring/render parity.

TOML schema DSL (#138)

  • TOML schema authoring โ€” schemas may now be authored in TOML as an additive alternative to TypeQL. A new Rust/PyO3 toml_to_typeql transpiles a TOML document to canonical TypeQL, which feeds the single existing parse path, so the intermediate representation, renderers, and generated packages are unchanged. Equivalent TOML and .tql schemas produce byte-for-byte identical packages. .tql authoring remains fully supported.
  • Full schema surface โ€” the DSL covers attributes (value types, sub, abstract, @regex/@values/@range), entities (owns with @key/@unique/@card, plays with optional per-plays @card, sub, abstract), relations (roles with per-role @card and as super-role overrides, owns, relation-level plays, sub, abstract), functions (signature plus verbatim body), and structs.
  • Generator routing โ€” generate_models transpiles a .toml source by file suffix, or for raw text via an explicit format="toml" argument.
  • Field-level diagnostics โ€” a semantic validation pass rejects malformed TOML with a clear ValueError naming the offending field or type (unknown value type, value/sub conflict, dangling sub parent, missing role player, empty struct, malformed function body) before any TypeQL is emitted.

Node.js typed model layer (#124)

  • Branded attributes โ€” class Name extends attr.String("name") {} defines a hard-typed attribute whose class is nominally distinct from other attributes (Name is not interchangeable with Email or raw string). One factory per TypeDB value type; the mandatory name is both the schema attribute name and the compile-time brand.
  • Typed Entity / Relation classes โ€” class Person extends Entity("person", { name: field(Name, Key), age: field(Age).optional() }) {} yields typed construction and field reads, mirroring the Python class surface. Relations support multi-player role(...) declarations.
  • Descriptor emission โ€” typed models emit registration descriptors byte-identical to the Python facade (verified against the shared parity fixture), so the same model definition drives the existing dynamic managers.

[1.4.5] - 2026-05-21

Bug Fixes

Python ORM
  • Relation role-player hydration โ€” relation role players fetched as IID-only placeholders now hydrate correctly without requiring their own nested role players (#126).
  • Optional relation roles โ€” Relation.manager(...).all() / fetch queries now include relations whose optional roles have no players (#127).
  • Optional role validation โ€” omitted optional roles normalize to None instead of leaking class-level RoleRef defaults, while required roles are still rejected when missing.
  • Role-player deduplication โ€” relation role players are deduplicated by IID when available, preserving distinct attribute-less relation players.
  • TypeDB driver compatibility โ€” added create_driver_options() helper and exported it from type_bridge to support driver option construction across supported TypeDB driver APIs.
Rust Core / Server
  • Raw TypeQL endpoint โ€” restored POST /query/raw on the Rust server, parsing TypeQL text into clauses before running the existing query pipeline.
  • Server configuration โ€” TypeDB connection settings can now be overridden with TYPEDB_ADDRESS, TYPEDB_DATABASE, TYPEDB_USERNAME, and TYPEDB_PASSWORD.
  • Clippy cleanup โ€” updated ORM role collection code to satisfy current Rust lints.

Compatibility

  • Pinned TypeDB runtime โ€” Python dependency now pins typedb-driver==3.10.0.
  • Python version bounds โ€” package metadata now declares >=3.13,<3.15.
  • Integration environment โ€” Docker Compose defaults now use TypeDB 3.10.4 and expose a configurable TYPEDB_PORT.

Testing & Tooling

  • Pinned Docker-in-Docker integration runner โ€” added Dockerfile.integration, docker-compose.dind.yml, and test-integration-dind.sh for reproducible Python 3.13.5 + TypeDB 3.10.4 integration tests.
  • Added regression coverage for relation role-player hydration, optional relation fetches, raw proxy queries, and server environment overrides.

[1.4.4] - 2026-04-09

New Features

Cross-type attribute lookup (PR #117)

Entity.has / Relation.has / <Concrete>.has โ€” find all instances that own a given attribute, optionally filtered by value or expression.

Python ORM โ€” type_bridge.crud.has_lookup
  • Cross-type form โ€” Entity.has(db, Name) returns mixed concrete subtypes across all entities owning Name.
  • Concrete-class narrowing โ€” HLPerson.has(db, Name) narrows to that type and its TypeDB subtypes via isa polymorphism. Abstract base subclasses get subtype matching for free.
  • Role-player hydration โ€” relation results always include hydrated role players. Entity lookups remain single-query; relations are re-fetched per result through concrete_class.manager(connection).get(_iid=iid).
  • Attribute.get_owners() โ€” static discovery of attribute owners without a database connection, backed by a reverse _attribute_owners index in ModelRegistry.

[1.4.3] - 2026-04-05

Bug Fixes

Rust Server โ€” type-bridge-server
  • fix: extract_crud_info() now reports the write-target type for Match + Insert/Put queries (#121)
Rust Core โ€” type-bridge-core-lib
  • refactor: use idiomatic match guards in validation.rs

[1.4.2] - 2026-03-04

Rust Server โ€” type-bridge-server
  • CrudInfo on RequestContext โ€” operation, type_name, type_kind, attribute_names, iid
  • CrudInterceptor trait with on_crud_request / on_crud_response and should_intercept
  • CrudInterceptorAdapter bridges CrudInterceptor into the existing Interceptor chain

[1.4.1] - 2026-03-03

New Features

Lifecycle Hook System (PR #118, closes #116)

Three-layer hook system for reacting to CRUD lifecycle events (audit logging, validation, cache invalidation, async notifications).

Python ORM โ€” type_bridge.crud.hooks
  • CrudEvent enum โ€” PRE_INSERT, POST_INSERT, PRE_UPDATE, POST_UPDATE, PRE_DELETE, POST_DELETE, PRE_PUT, POST_PUT
  • LifecycleHook protocol โ€” implement only the methods you need (pre_insert, post_delete, etc.)
  • HookCancelled exception โ€” raise in a pre-hook to abort the operation
  • Per-manager registration โ€” manager.add_hook(hook) / manager.remove_hook(hook), chainable
  • should_run(event, sender) filtering by event type or model class
  • Pre-hooks run in registration order; post-hooks run in reverse order (middleware unwinding)
  • Zero overhead when no hooks are registered
Rust ORM โ€” type-bridge-orm
  • LifecycleHook trait with HookContext, PreHookResult (Continue/Reject), and HookRunner
  • Integrated into EntityManager and RelationManager via add_hook()
  • Same semantics as the Python layer (registration-order pre-hooks, reverse-order post-hooks)

Put (Upsert) Clause โ€” type-bridge-core-lib

  • Added Clause::Put(Vec<Statement>) variant for idempotent insert (upsert) operations
  • Parser: parse_put_clause with keyword lookahead in both parse_patterns and parse_statements
  • Compiler: Generates put\n<statements>; TypeQL output
  • Validation: Reuses Insert validation rules (Clause::Insert | Clause::Put)
  • Full roundtrip support (parse โ†’ AST โ†’ compile โ†’ parse)

Refactoring

Server API Simplification โ€” type-bridge-server

  • Removed standalone CRUD module (/entities/*, /relations/* endpoints, CrudQueryBuilder, raw query support) โ€” superseded by the interceptor-based design
  • Removed crud_builder benchmark and criterion dev-dependency
  • Server now has 4 endpoints: POST /query, POST /query/validate, GET /health, GET /schema

[1.4.0] - 2026-02-20

Highlights

  • 5 new Rust crates: core-lib, orm, orm-derive, server, and python (PyO3 bindings)
  • Up to 40x faster validation and 2.5x faster query compilation via the Rust backend
  • Async Rust ORM with derive macros, chainable queries, and batch operations
  • Query-intercepting proxy server with REST endpoints
  • MkDocs Material documentation site

New Features

Rust Core โ€” type-bridge-core-lib (PRs #95, #101-#108)

  • TypeQL schema parser with inheritance resolution and PyO3 bindings
  • TypeQL query parser with bidirectional AST roundtrip
  • Schema-aware query validation with statement and pattern validators
  • Rust-backed value coercion and format_value
  • Custom validation rules with portable JSON DSL
  • Wired Rust core into Python compiler and validation pipeline

Async Rust ORM โ€” type-bridge-orm (PR #114)

  • Async ORM with entity CRUD and mock-testable session layer
  • Derive macros โ€” #[derive(TypeBridgeEntity)], #[derive(TypeBridgeRelation)], #[derive(TypeBridgeAttribute)]
  • Chainable query builders with expression filtering and aggregation
  • Schema management โ€” registration, generation, diff, and sync
  • Abstract types with inheritance and code generation
  • Batch operations โ€” insert_many, delete_many, update_many
  • FieldRef<A> for type-safe query field references
  • include_schema! proc-macro for compile-time TQL codegen
  • Schema introspection from live TypeDB database
  • Group-by queries with GroupByResult
  • Role player field access for relation query filtering
  • Expression helpers โ€” in_range(), startswith(), endswith()
  • Connection pooling with Database::into_shared()
  • Serde support on all ORM model types
  • Structured tracing spans on all public methods

Query Intercept Proxy โ€” type-bridge-server (PR #109)

  • REST CRUD endpoints with schema-aware query building
  • CrudQueryBuilder PyO3 class for TypeQL generation from Python
  • Extensible library/framework โ€” pluggable QueryExecutor, Interceptor, SchemaSource
  • 207 tests with 100% MC/DC coverage

Performance: Python vs Rust

Validation

Operation Python Rust Speedup
Single type name 1.89 us 354.75 ns 5.3x
Long name (100+ chars) 24.90 us 620.52 ns 40.1x
Batch 1,000 names 5.32 ms 266.80 us 19.9x
Batch 5,000 names 28.02 ms 1.33 ms 21.1x

Query Compilation (via serde bridge)

Operation Python Rust Speedup
Standalone update 93.28 us 37.82 us 2.5x
Large batch (200 clauses) 2.26 ms 1.07 ms 2.1x
Heavy insert (100x6) 1.71 ms 896.19 us 1.9x

Documentation & CI

  • MkDocs + Material documentation site with auto-generated API reference (PR #98)
  • Rust crate CI with multi-platform wheel builds โ€” Linux (x86_64, aarch64), macOS (x86_64, aarch64), Windows (x86_64) (PR #95)
  • Comprehensive benchmark suite with TOML storage, comparison reports, and markdown generation (PR #103)
  • Codecov integration for Rust coverage tracking (PR #109)

Bug Fixes

  • Resolve Rust 1.93.0 clippy lint errors
  • Pin Python 3.13 for Rust CI jobs and fix coverage script
  • Add version specifiers to inter-crate path dependencies for crates.io publishing
  • Make release workflow idempotent (skip already-published packages)

[1.3.0] - 2026-02-09

New Features

API DTO Generator (PRs #96, #97, #99, #100)

  • Pydantic DTO generation from TypeQL schemas โ€” Generate typed Create/Out/Patch DTOs directly from parsed schemas
  • Composite DTOs โ€” CompositeEntityConfig for flat/merged DTOs across entity types with name clash validation
  • Per-variant field requiredness overrides โ€” FieldOverride and EntityFieldOverride to control field requiredness per DTO variant (Create, Out, Patch)
  • skip_variants โ€” Skip generating specific variant classes while keeping the type Literal enum
  • extra_fields_out โ€” Per-variant override for extra fields on Out DTOs
  • strict_out_models โ€” Flag for required fields in Out DTOs
  • Reusable Jinja macros โ€” Refactored templates into _dto_macros.jinja
  • CLI support โ€” python -m type_bridge.generator now supports DTO generation

Date Arithmetic and Query-Level Arithmetic Expressions

  • Date arithmetic โ€” __add__, __radd__, __sub__ on Date for Duration arithmetic, matching DateTime/DateTimeTZ
  • ArithmeticExpr โ€” New expression class with helpers (add, sub, mul, div, mod, pow_) for TypeQL infix operators
  • ArithmeticValue AST node and compiler support

Improvements

  • TypeDB 3.8.0 stable โ€” Bumped from 3.8.0-rc0 to 3.8.0 release
  • TypeDB driver 3.8.0 โ€” Upgraded typedb-driver dependency to 3.8.0
  • Expression module cleanup โ€” Improved handling across boolean, comparison, and string expression modules
  • Field module cleanup โ€” Enhanced field handling in base and role modules

Housekeeping

  • Applied ruff formatting to all test files
  • Added .coverage to .gitignore (was accidentally tracked)

[1.2.7] - 2026-02-03

New Features

TypeDB 3.8.0 Support (PR #93)

  • Full compatibility with TypeDB 3.8.0
  • Updated driver integration

Performance Improvements

Batch Operations Optimization

  • Batch delete operations with disjunctive IID matching
  • Batch entity inserts/puts into single query
  • Optimized IID retrieval with single-query insert+fetch

Bug Fixes

  • HydrationError handling - Raise HydrationError instead of silently swallowing exceptions
  • Variable collision prevention - Use double underscore separator to prevent variable collisions
  • TypeDB 3.x relation syntax - Use correct relation insert syntax with links keyword
  • Multi-variable let fix - Remove incorrect parentheses in multi-variable let assignment
  • Polymorphic attributes - Restore polymorphic attribute fetching with nested wildcard

Refactoring

  • Consolidate duplicated code and fix Python 3.13 warnings
  • Unify entity identification logic across managers
  • Extract shared attribute-to-AST logic into TypeDBType
  • Remove .c accessor for direct field access

Code Quality

  • Remove all type: ignore comments for full type safety

Testing

  • Add recursive relation tests
  • Add validation performance benchmarks

[1.2.6] - 2026-02-01

New Features

Polymorphic Role Player Type Resolution (PR #92)

  • Role players now resolve to their concrete Python types
  • When querying relations with abstract role types, role players are resolved to concrete types (e.g., Person instead of Profile)
  • Uses TypeQL label() function to fetch type labels and resolve to correct Python class
  • Location: type_bridge/crud/relation/manager.py

Relations as Role Players

  • Fixed hydration for relations serving as role players
  • Relations can now properly participate as role players in other relations
  • Comprehensive test suites added for this pattern
  • Location: type_bridge/crud/relation/manager.py

Improvements

Modular Helper Methods (PR #92)

  • Extracted reusable helper methods for DRY refactoring
  • _resolve_entity_class_from_label() - Resolves concrete types using TypeQL label() function
  • _hydrate_entity_from_data() - Helper for role player instantiation
  • Eliminates duplicate code in get() and get_by_iid() methods

Generator Enhancements (PR #92)

  • Improved code generation for relations
  • Role cardinality annotations now properly rendered
  • Docstrings and type annotations rendering improvements
  • Location: type_bridge/generator/

Bug Fixes

Polymorphic Role Validation (PR #92)

  • Fixed polymorphic role validation and role player IIDs
  • Correct handling of abstract types in role player resolution
  • Fixed role player IID extraction in polymorphic queries

Test Fixes (PR #92)

  • Fixed manager.count() โ†’ manager.filter().count() in tests
  • Renamed attribute types to avoid naming collisions

Testing

  • 19 new integration tests (tests/integration/queries/test_social_network_queries.py)
  • Deep inheritance (3-level: Entity โ†’ Profile โ†’ Person/Organization)
  • Self-referential symmetric relations (Friendship)
  • Geographic hierarchy chains (Person โ†’ City โ†’ Country)
  • Polymorphic role players with concrete type verification
  • Multi-value attributes with @card(0..*)
  • Chained relations and complex filter combinations

Key Files Modified

  • type_bridge/crud/relation/manager.py - Polymorphic role player resolution
  • type_bridge/generator/render/ - Role cardinality and annotations rendering
  • tests/integration/queries/test_social_network_queries.py - New comprehensive tests

[1.2.5] - 2026-01-31

New Features

IID-preferring Role Player Matching (PR #91)

  • RelationManager now prefers IID for role player matching
  • Uses IID for precise matching when available
  • Falls back to key attribute matching when IID not set
  • Raises clear ValueError when neither IID nor key attributes available
  • Location: type_bridge/crud/relation/manager.py

Affected Methods: insert(), put(), update(), delete() and *_many variants

Documentation

  • Updated role player matching docs in docs/SKILL.md and docs/api/crud.md

[1.2.4] - 2026-01-30

New Features

TypeDB 3.8.0 Built-in Functions (PR #88)

  • Added support for TypeDB 3.8.0 built-in functions
  • Identity functions: iid(), label()
  • Math functions: abs_(), ceil(), floor(), round_()
  • Collection functions: len_(), max_(), min_()
  • Location: type_bridge/expressions/builtins.py

Usage Example:

from type_bridge.expressions import iid, label, abs_, ceil, floor

# Get entity IID
query = Person.manager(db).filter(iid() == "0x1a2b3c").execute()

# Use math functions
query = Person.manager(db).filter(abs_(Age.value) > 18).execute()

Unicode XID Identifier Validation (PR #88)

  • Added Unicode identifier validation for TypeDB 3.8.0 compatibility
  • Validates identifiers follow Unicode XID_Start/XID_Continue rules
  • Ensures TypeQL identifiers are compatible with TypeDB 3.8.0
  • Clear error messages for invalid identifiers
  • Location: type_bridge/validation.py

Bug Fixes

Value Extraction Fix (PR #88)

  • Fixed value extraction for _Value concepts
  • Changed from .as_value() to .get() for proper value extraction
  • Fixes issues with function return values and aggregations
  • Location: type_bridge/session.py

Driver Initialization Warning Fix (PR #88)

  • Fixed "Failed to initialize logging" warning
  • Suppresses fd 2 (stderr) during TypeDB driver initialization
  • Eliminates spurious warning messages on startup
  • Location: type_bridge/typedb_driver.py

Documentation

  • Added AI Assistant Skill Documentation (docs/SKILL.md)
  • Guidelines for using TypeBridge with AI code assistants

Testing

  • 32 new unit tests for builtin expressions
  • 7 new integration tests for iid() and label() functions
  • All existing tests pass with TypeDB 3.8.0-rc0
  • Fixed hardcoded port 1729 in tests to use TEST_DB_ADDRESS

CI/CD

  • Updated CI to TypeDB 3.8.0-rc0
  • All tests now run against TypeDB 3.8.0-rc0

Key Files Modified

  • type_bridge/expressions/builtins.py - New built-in function expressions
  • type_bridge/session.py - Value extraction fix
  • type_bridge/typedb_driver.py - Driver initialization fix
  • type_bridge/validation.py - Unicode identifier validation
  • docs/SKILL.md - New AI assistant documentation

[1.2.3] - 2025-12-28

New Features

Enhanced FunctionQuery System (PR #84)

  • Complete TypeQL query generation for function calls
  • FunctionQuery generates full match let queries with variable binding
  • Support for scalar returns, stream returns, and composite tuples
  • Query methods: to_call(), to_match_let(), to_fetch(), to_query()
  • Pagination support with limit/offset/sort
  • Location: type_bridge/expressions/functions.py

Usage Example:

from myschema.functions import count_artifacts, get_neighbor_ids

# Simple count
fn = count_artifacts()
query = fn.to_query()
# โ†’ match let $integer = count-artifacts(); fetch { "integer": $integer };

# Stream with pagination
fn = get_neighbor_ids(target_id="abc-123")
query = fn.to_query(limit=10, offset=5)

Driver Injection Support (PR #86)

  • Share TypeDB driver instances across Database objects
  • Optional driver parameter in Database.__init__()
  • Ownership tracking with _owns_driver flag for lifecycle control
  • Enables connection pooling and framework integration
  • Location: type_bridge/session.py

Benefits: - Resource efficiency (share one TCP connection) - Application-level connection pooling strategies - Centralized driver lifecycle management - Backwards compatible (default behavior unchanged)

Usage Example:

driver = TypeDB.driver("localhost:1729", Credentials("admin", "password"))

db1 = Database(database="project_a", driver=driver)  # Shares driver
db2 = Database(database="project_b", driver=driver)  # Shares driver

db1.close()  # Just clears reference
db2.close()  # Just clears reference
driver.close()  # Actually closes connection

@independent Annotation Support (PR #83)

  • Standalone attributes without entity/relation owners
  • Add independent = True ClassVar to attribute classes
  • Generates @independent annotation in TypeQL schema
  • Enables standalone attribute insertion and queries
  • Location: type_bridge/attribute/base.py

Usage Example:

class Language(String):
    """Can exist without an owner."""
    independent = True

# Generated TypeQL: attribute Language @independent, value string;

@range Validation and Schema Generation (PR #82)

  • Runtime validation with database enforcement
  • Integer and Double validate range_constraint ClassVar at initialization
  • Schema generation includes @range(min..max) annotations
  • Also generates @regex and @values annotations from ClassVars
  • Two-layer validation: Python-side (fail-fast) + TypeDB-side (enforcement)
  • Location: type_bridge/attribute/integer.py, type_bridge/attribute/double.py

Usage Example:

from typing import ClassVar

class Age(Integer):
    range_constraint: ClassVar[tuple[str | None, str | None]] = ("0", "150")

Age(200)  # Raises: ValueError: Age value 200 is above maximum 150

# Generated schema: attribute Age, value integer @range(0..150);

Batch IID Filtering (PR #81)

  • Django-style iid__in lookup for efficient batch queries
  • Filter entities/relations by multiple IIDs in single query
  • Role player filtering: employee__iid__in=[...]
  • Uses flat BooleanExpr to avoid stack overflow with many IIDs
  • Location: type_bridge/expressions/iid.py, type_bridge/crud/entity/manager.py

Usage Example:

# Fetch multiple entities by IID
persons = Person.manager(db).filter(iid__in=["0x1a2b3c", "0x4d5e6f"]).execute()

# Filter relations by role player IIDs
employments = Employment.manager(db).filter(employee__iid__in=["0x1a2b3c"]).execute()

Performance: O(1) query vs O(N) get_by_iid() calls.

TypeQL Annotation Validation (PR #86)

  • Comprehensive validation for schema annotations
  • @card: Validates min โ‰ค max, non-negative values, detects comma syntax
  • @regex: Validates patterns compile as valid regex
  • @values: Validates at least one value, detects duplicates
  • @range: Validates proper .. syntax, rejects comma/single-value
  • Clear, actionable error messages
  • Location: type_bridge/generator/parser.py

Bug Fixes

Code Generator Fixes (PR #86)

  • Fixed relation inheritance to include keys, uniques, and cardinalities
  • Child relations now inherit @key, @unique, and @card from parent
  • Ensures complete type definitions in generated code
  • Location: type_bridge/generator/render/relations.py

  • Fixed optional relation attributes in generated models

  • Correct type hints with | None for optional fields
  • Proper default values (e.g., timestamp: Timestamp | None = None)
  • Respects cardinality: @card(1) = required, no annotation = optional
  • Location: type_bridge/generator/render/relations.py

  • Fixed Python literal rendering for @range annotations

  • Range values output as numeric literals: (1, None) not ("1", null)
  • Fixed type hint from str | None to int | float | None
  • Location: type_bridge/generator/render/attributes.py

Query Generation Fixes (PR #84)

  • Fixed composite variable lists in FunctionQuery
  • Removed incorrect parentheses around variable lists
  • Correct: match let $a, $b in func()
  • Incorrect (previous): match let ($a, $b) in func()
  • Location: type_bridge/expressions/functions.py

Type Checking Fixes

  • Proper type annotations for ty type checker
  • Use type[Attribute] instead of generic type
  • Use type[Entity] | type[Relation] for model params
  • Core library passes ty with zero warnings
  • Location: type_bridge/crud/relation/lookup.py, type_bridge/schema/introspection.py

  • Added None checks for optional attributes

  • assert position is not None guards before accessing .value
  • Fixes pyright errors in tests
  • Location: tests/integration/crud/test_iid_feature.py

Development & Tooling

Project Restructuring

  • Moved Python package to repository root
  • Transitioned from monorepo (packages/python/) to root-level package
  • TypeScript split into separate type-bridge-ts repository
  • Simplified CI/CD configuration

Pre-commit Hooks

  • Comprehensive code quality automation
  • ruff linting and formatting
  • pyright type checking
  • ty type checker for enhanced type safety
  • Location: .pre-commit-config.yaml

Type Checker Configuration

  • Configured ty rules for metaclass compatibility
  • Overrides for tests/examples to handle metaclass-generated code
  • Rules: unknown-argument, unresolved-attribute, call-non-callable
  • Location: pyproject.toml [tool.ty.overrides]

Documentation

  • FunctionQuery documentation and integration tests
  • Comprehensive examples of query generation patterns
  • All function patterns tested (scalar, stream, composite)

  • Database driver injection guide

  • Connection pooling examples
  • Framework integration patterns

  • Generator relation cardinality documentation

  • Clarified @card behavior on relation attributes
  • Required vs optional attribute patterns

Testing

  • 1096 unit tests passing (100% pass rate)
  • All integration tests passing
  • 0 errors with pyright and ty type checkers

Key Files Modified

  • type_bridge/expressions/functions.py - Enhanced FunctionQuery
  • type_bridge/session.py - Driver injection support
  • type_bridge/generator/parser.py - Annotation validation
  • type_bridge/generator/render/relations.py - Inheritance and optional attributes
  • type_bridge/generator/render/attributes.py - Python literal rendering
  • type_bridge/crud/relation/lookup.py - Type annotations
  • type_bridge/schema/introspection.py - Type annotations
  • type_bridge/attribute/base.py - @independent support
  • type_bridge/attribute/integer.py - @range validation
  • type_bridge/attribute/double.py - @range validation
  • .pre-commit-config.yaml - Pre-commit hooks configuration
  • pyproject.toml - ty type checker configuration

[1.2.2] - 2025-12-25

Bug Fixes

RelationManager IID Correlation Fix (Issue #78)

  • Fixed incorrect IID assignment in RelationManager.all()
  • Problem: All relations were getting the same IID values for their role players instead of unique IIDs for each relation
  • Root cause: _populate_iids method didn't properly correlate query results to the correct relation instances
  • Solution: Capture key attribute values as variables in the query and build a lookup map for correlating results back to the correct relations
  • Impact: Critical for code relying on role player _iid values for deduplication or correlation
  • Example: Multiple friendships now correctly show unique IIDs for each person instead of all showing the same IIDs
  • Location: type_bridge/session.py, type_bridge/crud/relation/manager.py

Testing

  • Added 133 lines of regression tests for Issue #78
  • Verifies multiple relations each get their own unique IIDs

Key Files Modified

  • type_bridge/session.py - Added value extraction for attribute concepts in _extract_concept_row
  • type_bridge/crud/relation/manager.py - Fixed IID correlation logic (198 additions, 134 deletions)
  • tests/integration/crud/test_iid_feature.py - Added regression tests for Issue #78

[1.2.1] - 2025-12-25

Bug Fixes

Stack Overflow Fix for __in Lookup (Issue #76)

  • Fixed TypeDB stack overflow when using __in lookup with many values (75+)
  • Root cause: Deeply nested binary OR expressions ((((a or b) or c) or d)...) caused TypeDB query planner to stack overflow
  • Solution: Use flat BooleanExpr structure for OR operations
  • Example: manager.filter(name__in=["Alice", "Bob", ...150 names]) now works reliably
  • Location: type_bridge/crud/entity/manager.py, type_bridge/crud/relation/lookup.py, type_bridge/expressions/boolean.py
  • Added automatic flattening of BooleanExpr operations
  • BooleanExpr.and_() and BooleanExpr.or_() now automatically flatten operands of the same operation type
  • Prevents deeply nested expression trees
  • Improves query compilation performance

Testing

  • Added 249 new tests for BooleanExpr flattening and __in lookup edge cases
  • All tests passing

Key Files Modified

  • type_bridge/crud/entity/manager.py - Flat OR structure for __in lookups
  • type_bridge/crud/relation/lookup.py - Flat OR structure for relation lookups
  • type_bridge/expressions/boolean.py - Automatic flattening in and_() and or_()
  • tests/unit/crud/test_lookup_parser.py - Entity lookup tests (37 tests)
  • tests/unit/crud/test_role_lookup_parser.py - Relation lookup tests (31 tests)
  • tests/unit/expressions/test_boolean_expr.py - BooleanExpr flattening tests (181 tests)

[1.2.0] - 2025-12-22

New Features

TypeDB 3.0 Structs Support (PR #71)

  • Parse and generate Python code for TypeDB struct types
  • Structs are value types composed of named fields
  • Full code generator support for struct definitions
  • Location: type_bridge/generator/

Additional Annotations Support (PR #71)

  • @range annotation rendering in code generator
  • Support for @range(min..max) constraints on attributes
  • Renders as validation metadata in generated code

Role Player IIDs (PR #70)

  • Populate IIDs on role player entities when fetching relations
  • Role players now have their _iid field populated automatically
  • Enables direct IID-based lookups on role players

Generator CLI Enhancement (PR #70)

  • New --schema-path CLI option for code generator
  • Specify custom path for schema file in generated output

Batch Delete Error Handling

  • strict parameter for delete_many - Optional error handling for batch deletes
  • When strict=True, raises error if any entity not found
  • When strict=False (default), silently skips missing entities

Performance Improvements

Batch Query Optimizations (PR #75)

  • 50-100x improvement for bulk operations
  • Batch update_with operations to reduce round-trips
  • Batch _populate_iids for efficient IID resolution
  • Significant performance gains for large datasets

N+1 Query Fix (PR #73)

  • Fix N+1 query problem in entity IID/type resolution
  • Previously: 1 query per entity for IID resolution
  • Now: Single batched query for all entities
  • Major performance improvement for all() and filter().execute()

Batched CRUD Operations

  • Batched update_many and delete_many operations
  • Efficient batch processing instead of per-entity queries
  • Reduced database round-trips

Bug Fixes

  • None check in delete_many - Add None check for entity in batched delete query to prevent errors when entity list contains None values

Key Files Modified

  • type_bridge/generator/parser.py - Struct parsing support
  • type_bridge/generator/render/ - Struct code generation
  • type_bridge/generator/__main__.py - --schema-path CLI option
  • type_bridge/crud/entity/manager.py - Batch operations, strict parameter
  • type_bridge/crud/entity/query.py - Batch IID population
  • type_bridge/crud/relation/manager.py - Role player IID population

[1.1.0] - 2025-12-19

New Features

Polymorphic Entity Instantiation

  • Querying a supertype now returns proper subtype instances (Issue #65)
  • Artifact.manager(db).all() returns a mix of UserStory, DesignAspect, etc.
  • Each entity has the correct Python type with all subtype-specific attributes populated
  • IIDs and type information correctly extracted for each subtype

Usage Example:

# Define type hierarchy
class Artifact(Entity):
    flags = TypeFlags(abstract=True)
    name: Name = Flag(Key)

class UserStory(Artifact):
    story_points: StoryPoints

class DesignAspect(Artifact):
    priority: Priority

# Query supertype - get proper subtypes back
artifacts = Artifact.manager(db).all()
for artifact in artifacts:
    print(type(artifact))  # UserStory, DesignAspect, etc.
    print(artifact.name)   # All have base attributes
    if isinstance(artifact, UserStory):
        print(artifact.story_points)  # Subtype-specific attributes

Refactoring

Jinja2 Templates for Code Generation

  • Code generator now uses Jinja2 templates instead of string concatenation
  • 6 new templates: attributes, entities, relations, functions, package_init, registry
  • Significant code reduction in render modules:
    • registry.py: 578 โ†’ 156 lines (-422)
    • package.py: 116 โ†’ 61 lines (-55)
    • entities.py: 234 โ†’ 198 lines (-36)

Typer CLI

  • Generator and migration CLIs migrated to Typer
  • Improved help messages and command structure
  • Better argument parsing and validation

Dependencies

  • Added jinja2>=3.1.0 - Template engine for code generation
  • Added typer>=0.15.0 - CLI framework for generator and migration tools

Key Files Modified

  • type_bridge/crud/entity/manager.py - Polymorphic instantiation in get()
  • type_bridge/crud/entity/query.py - Polymorphic instantiation in execute()
  • type_bridge/crud/utils.py - resolve_entity_class() utility
  • type_bridge/generator/__main__.py - Typer CLI
  • type_bridge/generator/render/ - Jinja2 template integration
  • type_bridge/generator/templates/ - 6 new Jinja2 templates
  • type_bridge/migration/__main__.py - Typer CLI with subcommands

[1.0.1] - 2025-12-19

New Features

TypeDB IID Support

  • Expose TypeDB Internal ID (IID) on entity and relation instances
  • _iid field automatically populated when entities/relations are fetched from database
  • New get_by_iid(iid: str) method on EntityManager and RelationManager
  • IID populated from get(), filter().execute(), and all() operations

Usage Example:

# Insert entity
person = Person(name=Name("Alice"), age=Age(30))
Person.manager(db).insert(person)

# Fetch - IID is automatically populated
fetched = Person.manager(db).get(name="Alice")
print(fetched[0]._iid)  # '0x1e00000000000000000000'

# Direct IID lookup
person = Person.manager(db).get_by_iid("0x1e00000000000000000000")

Bug Fixes

  • Fixed relation IID assignment order - Set _iid after role player assignments to prevent Pydantic revalidation from resetting the value

Key Files Modified

  • type_bridge/session.py - IID extraction functions
  • type_bridge/crud/entity/manager.py - get_by_iid() method
  • type_bridge/crud/entity/query.py - IID extraction from results
  • type_bridge/crud/relation/manager.py - get_by_iid() method
  • type_bridge/crud/relation/query.py - IID extraction from results

[1.0.0] - 2025-12-15

New Features

Django-style Migration System

  • Complete migration framework for TypeDB schema evolution
  • Auto-generate migrations from Python model changes
  • Apply and rollback migrations with transaction safety
  • Track migration state in TypeDB database
  • CLI commands: type-bridge makemigrations, type-bridge migrate
  • Location: type_bridge/migration/ (2872 lines)

  • Migration Operations

  • AddAttribute - Add new attribute types
  • AddEntity - Add new entity types
  • AddRelation - Add new relation types with roles
  • AddOwnership - Add attribute ownership to types
  • AddRolePlayer - Add role players to relations
  • RemoveAttribute, RemoveEntity, RemoveRelation - Remove types
  • RunTypeQL - Execute raw TypeQL for custom migrations
  • All operations support forward and rollback
  • Location: type_bridge/migration/operations.py

  • Migration Generator

  • Auto-detect schema changes by comparing Python models to database
  • Generate migration files with operations
  • Support for incremental migrations (detect only changes)
  • Location: type_bridge/migration/generator.py

  • Migration Executor

  • Apply pending migrations in order
  • Rollback migrations in reverse order
  • Dry-run mode for previewing changes
  • sqlmigrate for viewing generated TypeQL
  • Location: type_bridge/migration/executor.py

  • Migration State Tracking

  • Track applied migrations in TypeDB
  • Location: type_bridge/migration/state.py

  • Model Registry

  • Register models for migration tracking
  • Auto-discover models from modules
  • Location: type_bridge/migration/registry.py

Schema Introspection

  • Query existing schema from TypeDB database
  • Introspect entities, relations, attributes, and ownerships
  • TypeDB 3.x compatible queries
  • Model-aware introspection for efficient checking
  • Location: type_bridge/schema/introspection.py (527 lines)

Breaking Change Detection

  • Analyze schema changes for safety
  • Detect breaking vs safe changes
  • Categories: BREAKING, SAFE, WARNING
  • Check role player narrowing, type removal, etc.
  • Location: type_bridge/schema/breaking.py (411 lines)

Enhanced Schema Diff

  • Improved schema comparison
  • Compare by TypeDB type name instead of Python object identity
  • Detect modified entities, relations, and role players
  • Track attribute and ownership changes
  • Location: type_bridge/schema/info.py, type_bridge/schema/diff.py

Bug Fixes

TypeDB 3.x Compatibility

  • Fixed schema comparison using Python object identity instead of type name
  • SchemaInfo.compare() now correctly matches entities/relations by type name

  • Fixed migration executor to execute operations separately

  • TypeDB 3.x doesn't allow multiple define blocks in single query

  • Fixed schema introspection to query ownership from schema definition

  • Uses match {type_name} owns $a; for schema queries

  • Fixed migration state tracking for TypeDB 3.x @key semantics

  • Uses composite key (migration_id) instead of dual @key attributes

Testing

  • All 391 integration tests passing
  • Added comprehensive migration test suite
  • Added role player diff tests
  • Added schema introspection tests

Key Files Added

  • type_bridge/migration/__init__.py - Migration module exports
  • type_bridge/migration/__main__.py - CLI commands
  • type_bridge/migration/base.py - Migration base class
  • type_bridge/migration/operations.py - Migration operations
  • type_bridge/migration/generator.py - Auto-generation
  • type_bridge/migration/executor.py - Apply/rollback
  • type_bridge/migration/loader.py - Load migration files
  • type_bridge/migration/state.py - State tracking
  • type_bridge/migration/registry.py - Model registry
  • type_bridge/schema/introspection.py - Schema introspection
  • type_bridge/schema/breaking.py - Breaking change detection
  • tests/integration/migration/ - Migration integration tests
  • tests/integration/schema/test_role_player_diff.py - Role player tests

Usage Example

from type_bridge.migration import MigrationGenerator, MigrationExecutor
from type_bridge import Database

db = Database("localhost:1729", "mydb")

# Generate migration from models
generator = MigrationGenerator(db, "./migrations")
generator.generate(models=[Person, Company], name="initial")

# Apply migrations
executor = MigrationExecutor(db, "./migrations")
results = executor.migrate()

# Rollback
executor.rollback()

CLI Usage

# Generate migrations
type-bridge makemigrations ./migrations --models myapp.models

# Apply migrations
type-bridge migrate ./migrations

# Show migration status
type-bridge showmigrations ./migrations

# Preview TypeQL
type-bridge sqlmigrate ./migrations 0001_initial

[0.9.4] - 2025-12-12

New Features

Debug Logging Support (Issue #43)

  • Added comprehensive logging throughout TypeBridge using Python's standard logging module
  • See generated TQL queries during CRUD operations
  • Hierarchical logger structure for fine-grained control
  • Documentation: docs/api/logging.md

Bug Fixes

Type Safety Improvements

  • Fixed pyright errors for TransactionType.name access in session.py
  • Added _tx_type_name() helper function for type-safe transaction type logging

Documentation

  • Added docs/api/logging.md - Comprehensive logging configuration guide
  • Updated docs/DEVELOPMENT.md with logging section

Key Files Modified

  • type_bridge/session.py - Fixed type errors, added logging
  • type_bridge/query.py - Added logging
  • type_bridge/validation.py - Added logging
  • type_bridge/schema/manager.py - Added logging
  • type_bridge/schema/migration.py - Added logging
  • type_bridge/crud/entity/manager.py - Added logging
  • type_bridge/crud/entity/query.py - Added logging
  • type_bridge/crud/entity/group_by.py - Added logging
  • type_bridge/crud/relation/manager.py - Added logging
  • type_bridge/crud/relation/query.py - Added logging
  • type_bridge/crud/relation/group_by.py - Added logging
  • type_bridge/generator/__main__.py - Added logging
  • type_bridge/generator/render/attributes.py - Added logging
  • type_bridge/generator/render/entities.py - Added logging
  • type_bridge/generator/render/relations.py - Added logging
  • type_bridge/models/entity.py - Added logging
  • type_bridge/models/relation.py - Added logging
  • docs/api/logging.md - New documentation
  • docs/DEVELOPMENT.md - Added logging section

[0.9.3] - 2025-12-12

Documentation

@key Attribute Requirement for update() (Issue #45)

  • Added prominent documentation explaining that update() requires @key attributes
  • New section "Important: @key Attributes Required for update()" in CRUD docs
  • Clear examples showing proper @key attribute definition
  • Error scenarios documented: no @key defined, @key value is None
  • Guidance for UUID/ID fields as @key attributes
  • Cross-reference to Exception Handling section
  • Location: docs/api/crud.md (lines 369-413)

Key Files Modified

  • docs/api/crud.md - Added @key requirement documentation in Update Operations section

[0.9.2] - 2025-12-12

New Features

KeyAttributeError Exception (Issue #44)

  • Added KeyAttributeError exception for @key validation failures
  • Raised when @key attribute is None during update/delete
  • Raised when no @key attributes are defined on entity
  • Structured attributes: entity_type, operation, field_name, all_fields
  • Helpful error messages with hints for fixing issues
  • Inherits from ValueError for backward compatibility
  • Location: type_bridge/crud/exceptions.py

Testing

  • Added 7 unit tests for KeyAttributeError
  • 813 unit tests passing

Key Files Added/Modified

  • type_bridge/crud/exceptions.py - Added KeyAttributeError class
  • type_bridge/crud/__init__.py - Export KeyAttributeError
  • type_bridge/__init__.py - Export KeyAttributeError in public API
  • type_bridge/crud/entity/manager.py - Use KeyAttributeError
  • type_bridge/crud/entity/query.py - Use KeyAttributeError
  • tests/unit/exceptions/test_exceptions.py - Added KeyAttributeError tests

Usage Example

from type_bridge import KeyAttributeError

try:
    manager.update(entity_with_none_key)
except KeyAttributeError as e:
    print(f"Entity: {e.entity_type}")
    print(f"Operation: {e.operation}")
    print(f"Field: {e.field_name}")

[0.9.1] - 2025-12-11

New Features

Enhanced Code Generator (PR #53)

  • Registry Module - Generates registry.py with schema metadata as Python dictionaries
  • Entity/relation attributes, roles, and inheritance info
  • JSON Schema fragments for validation
  • Convenience lookup functions
  • Schema hash for change detection
  • Location: type_bridge/generator/render/registry.py

  • Enhanced Function Generation - Generic FunctionCallExpr[T] with precise return type hints

  • Support for all TypeDB function variations: stream, scalar, tuple, optional returns
  • Added bool to type mapping
  • Improved docstrings with return type documentation
  • Location: type_bridge/generator/render/functions.py

  • TypeQL Parser Enhancements

  • @independent attribute flag support
  • @range(min..max) constraint parsing (integers, floats, dates, datetimes, open-ended)
  • @card on plays declarations with inheritance
  • @card on relates declarations
  • // C-style comments alongside # comments
  • Comment annotations parsing (@prefix, @tags, etc.)
  • Location: type_bridge/generator/parser.py, type_bridge/generator/typeql.lark

Testing

  • Added comprehensive generator unit tests for annotations, functions, and registry
  • 1,268 total tests passing

Key Files Added/Modified

  • type_bridge/generator/render/registry.py - Registry module generation (new)
  • type_bridge/generator/annotations.py - Annotation parsing (new)
  • type_bridge/generator/render/functions.py - Enhanced function generation
  • type_bridge/generator/parser.py - Parser enhancements
  • type_bridge/generator/typeql.lark - Grammar updates
  • type_bridge/generator/models.py - New annotation models
  • type_bridge/expressions/functions.py - Generic FunctionCallExpr
  • docs/api/generator.md - Updated documentation

Contributors

  • @CaliLuke - Generator enhancements

[0.9.0] - 2025-12-11

New Features

Type-Safe Role Player Expressions (PR #42)

  • Type-safe role player field expressions
  • Access role player attributes with type safety: Employment.employee.age.gte(Age(30))
  • RoleRef class for class-level role access
  • RolePlayerFieldRef for type-safe attribute access
  • RolePlayerNumericFieldRef for numeric comparison methods
  • RolePlayerStringFieldRef for string-specific methods (contains, like, regex)
  • Location: type_bridge/fields/role.py

  • Django-style role-player lookup filters

  • Filter by role player attributes: filter(employee__age__gt=30)
  • Support for comparison operators: __eq, __gt, __lt, __gte, __lte
  • Support for string operators: __contains, __like, __regex
  • Location: type_bridge/crud/relation/lookup.py

  • Added order_by() method to EntityQuery and RelationQuery

  • Sort results by entity/relation attributes or role player attributes
  • Supports ascending (default) and descending (-field) order
  • Role-player sorting: order_by('employee__age', '-salary')
  • Location: type_bridge/crud/entity/query.py, type_bridge/crud/relation/query.py

  • Added public Relation.get_roles() method

  • Clean API for accessing relation roles without internal _roles access
  • Returns: dict[str, Role] mapping role names to Role instances
  • Location: type_bridge/models/relation.py

Bug Fixes

  • Fixed RelationQuery.filter() to support Django-style kwargs
  • Chained .filter() calls now properly support **filters parameter
  • Location: type_bridge/crud/relation/query.py

Testing

  • Added TestCombinedWithPagination integration tests
  • Added TestRoleMultiAttributeAccess unit tests
  • All type checks pass without suppressions (uses isinstance for type narrowing)
  • 806 unit tests + 377 integration tests = 1,183 total tests

Key Files Added/Modified

  • type_bridge/fields/role.py - RoleRef and RolePlayerFieldRef classes
  • type_bridge/crud/relation/lookup.py - Django-style lookup parser
  • type_bridge/crud/relation/query.py - RelationQuery with filter and order_by
  • type_bridge/crud/entity/query.py - EntityQuery with order_by
  • type_bridge/models/relation.py - Added get_roles() method
  • type_bridge/generator/render/relations.py - Updated generated code patterns
  • tests/unit/fields/test_role_ref.py - RoleRef unit tests
  • tests/integration/queries/test_role_field_expressions.py - Integration tests

Usage Examples

from type_bridge import Relation, Role, Entity, TypeFlags, String, Integer

class Age(Integer):
    pass

class Name(String):
    pass

class Person(Entity):
    flags = TypeFlags(name="person")
    name: Name = Flag(Key)
    age: Age | None = None

class Employment(Relation):
    flags = TypeFlags(name="employment")
    employee: Role[Person] = Role("employee", Person)

# Type-safe role player expression
results = Employment.manager(db).filter(
    Employment.employee.age.gte(Age(30))
).execute()

# Django-style lookup
results = Employment.manager(db).filter(employee__age__gt=30).execute()

# Combined with sorting and pagination
results = (
    Employment.manager(db)
    .filter(Employment.employee.age.gte(Age(25)), salary__gte=80000)
    .order_by("employee__age", "-salary")
    .limit(10)
    .execute()
)

[0.8.1] - 2025-12-11

New Features

TypeDB Function Support in Code Generator

  • Parse TypeQL fun declarations with parameters and return types
  • Generate Python function wrappers that return FunctionCallExpr objects
  • Auto-generate functions.py module when functions are defined in schema
  • Support for all TypeDB data types (string, integer, date, datetime, double, boolean, decimal, duration)
  • Location: type_bridge/generator/render/functions.py

  • Added FunctionCallExpr class for building function calls in queries

  • New expression type for calling TypeDB functions
  • Location: type_bridge/expressions/functions.py

Lark-based Parser

  • Migrated from regex-based parser to robust Lark grammar
  • Added formal grammar file (typeql.lark) for better maintainability
  • Improved handling of edge cases (whitespace, optional clauses)
  • Better support for TypeDB 3.0 features
  • Location: type_bridge/generator/typeql.lark, type_bridge/generator/parser.py

Bug Fixes

Parser Grammar Fixes

  • Fixed parsing of sub and @abstract in entity/relation bodies
  • Now correctly handles patterns like entity page @abstract, sub content,
  • Supports sub appearing anywhere in the type definition, not just at the start
  • Fixed parsing of @card annotations on plays and relates statements
  • Now correctly parses plays posting:post @card(1) and relates subject @card(1)

Testing

  • Added 136 new unit tests for function parsing and rendering
  • All 808 tests passing (520 unit + 288 integration)

Key Files Added/Modified

  • type_bridge/generator/typeql.lark - Formal TypeQL grammar (75 lines)
  • type_bridge/generator/parser.py - Rewritten with Lark integration
  • type_bridge/generator/models.py - Added FunctionSpec, ParameterSpec
  • type_bridge/generator/render/functions.py - Function code generation
  • type_bridge/expressions/functions.py - FunctionCallExpr class
  • type_bridge/expressions/__init__.py - Export FunctionCallExpr
  • type_bridge/generator/__init__.py - Expose function parsing API
  • tests/unit/generator/test_functions.py - Function unit tests

[0.8.0] - 2025-12-11

New Features

Code Generator (TypeQL โ†’ Python)

  • Added type_bridge.generator module for generating Python models from TypeQL schema files
  • Eliminates manual synchronization between .tql schemas and Python code
  • Write schema once in TypeQL, generate type-safe Python models automatically
  • Location: type_bridge/generator/

  • CLI interface for code generation

  • Usage: python -m type_bridge.generator schema.tql -o ./models/
  • Options: --version, --no-copy-schema, --implicit-keys
  • Location: type_bridge/generator/__main__.py

  • Programmatic API

  • generate_models(schema, output_dir) - Main generation function
  • parse_tql_schema(schema_content) - Parse TypeQL to intermediate representation
  • Location: type_bridge/generator/__init__.py

  • Full TypeDB 3.x schema support

  • All value types: string, integer, double, decimal, boolean, date, datetime, datetime-tz, duration
  • Entity and relation inheritance (sub declarations)
  • Abstract types (@abstract)
  • Attribute constraints: @key, @unique, @card, @regex, @values
  • Role definitions and plays declarations
  • Comment annotations for customization (# @prefix:, # @internal)

  • Generated package structure

    output_dir/
    โ”œโ”€โ”€ __init__.py      # Package exports, SCHEMA_VERSION, schema_text()
    โ”œโ”€โ”€ attributes.py    # Attribute class definitions
    โ”œโ”€โ”€ entities.py      # Entity class definitions
    โ”œโ”€โ”€ relations.py     # Relation class definitions
    โ””โ”€โ”€ schema.tql       # Copy of original schema
    

Bug Fixes

Optional Attribute Update Fix

  • Fixed silent update failures for optional attributes (Resolves #47)
  • Previously: Updating an entity with an optional attribute set to None could silently fail
  • Now: Properly handles None values in update operations
  • Location: type_bridge/crud/entity/manager.py

Testing

  • Added comprehensive generator test suite
  • 62 unit tests covering parser, naming utilities, and renderers
  • 18 integration tests verifying generated code imports and executes correctly
  • Test fixtures with complex TypeQL schemas
  • Location: tests/unit/generator/, tests/integration/generator/

  • Expanded lookup filter tests

  • Additional test coverage for lookup filter parsing and execution
  • Location: tests/unit/crud/test_lookup_parser.py, tests/integration/queries/test_lookup_filters.py

Documentation

  • Added generator documentation
  • Complete API reference and usage guide
  • CLI reference and examples
  • Supported TypeQL features and cardinality mapping
  • Best practices for generated code management
  • Location: docs/api/generator.md

  • Updated project documentation

  • Added generator to project structure in CLAUDE.md
  • Updated README.md with code generator feature

Key Files Added/Modified

  • type_bridge/generator/__init__.py - Public API: generate_models(), parse_tql_schema()
  • type_bridge/generator/__main__.py - CLI interface
  • type_bridge/generator/models.py - ParsedSchema, AttributeSpec, EntitySpec, RelationSpec
  • type_bridge/generator/parser.py - TypeQL parser with inheritance resolution
  • type_bridge/generator/naming.py - kebab-case โ†’ PascalCase/snake_case utilities
  • type_bridge/generator/render/ - Code generation renderers (attributes, entities, relations, package)
  • type_bridge/crud/entity/manager.py - Optional attribute update fix
  • docs/api/generator.md - Generator documentation

Usage Examples

CLI Usage

# Generate models from a schema file
python -m type_bridge.generator schema.tql -o ./myapp/models/

# With options
python -m type_bridge.generator schema.tql \
    --output ./myapp/models/ \
    --version 2.0.0 \
    --implicit-keys id

Programmatic Usage

from type_bridge.generator import generate_models

# From a file path
generate_models("schema.tql", "./myapp/models/")

# From schema text
schema = """
define
entity person, owns name @key;
attribute name, value string;
"""
generate_models(schema, "./myapp/models/")

Using Generated Models

from myapp.models import attributes, entities, relations
from myapp.models import SCHEMA_VERSION, schema_text

# Access generated classes
person = entities.Person(name=attributes.Name("Alice"))

# Get schema version
print(SCHEMA_VERSION)  # "1.0.0"

[0.7.2] - 2025-12-10

Breaking Changes

New Exceptions for Delete Operations

  • Added EntityNotFoundError - Raised when deleting an entity that doesn't exist
  • Now raised for both keyed and keyless entities when no match is found
  • Previously: keyed entities silently succeeded, keyless raised ValueError
  • Subclass of LookupError

  • Added RelationNotFoundError - Raised when deleting a relation that doesn't exist

  • Raised when relation with given role players is not found
  • Previously: silently succeeded
  • Subclass of LookupError

  • Added NotUniqueError - Raised when keyless entity matches multiple records

  • Replaces ValueError for multiple match scenarios
  • Subclass of ValueError
  • Suggestion to use filter().delete() for bulk deletion

Migration Guide

# Handling non-existent entity deletion (NEW in v0.7.2)
from type_bridge import EntityNotFoundError, RelationNotFoundError, NotUniqueError

# Entity with @key that doesn't exist
try:
    manager.delete(nonexistent_entity)
except EntityNotFoundError:
    print("Entity was already deleted or never existed")

# Relation that doesn't exist
try:
    relation_manager.delete(nonexistent_relation)
except RelationNotFoundError:
    print("Relation was already deleted or never existed")

# Entity without @key matching multiple records
try:
    manager.delete(keyless_entity)
except NotUniqueError:
    print("Multiple entities matched - use filter().delete() for bulk deletion")

# Bulk delete with __in (migrating from v0.7.0)
# OLD: manager.delete_many(name__in=["Alice", "Bob"])
# NEW:
count = manager.filter(name__in=["Alice", "Bob"]).delete()

Key Files Modified

  • type_bridge/crud/exceptions.py - NEW - Exception classes
  • type_bridge/crud/__init__.py - Export exceptions
  • type_bridge/crud/entity/manager.py - Add existence check before delete
  • type_bridge/crud/relation/manager.py - Add existence check before delete
  • type_bridge/__init__.py - Export exceptions

[0.7.1] - 2025-12-09

Breaking Changes

Delete API Refactored to Instance-Based Pattern

  • Changed EntityManager.delete() signature
  • Old: delete(**filters) -> int (filter-based, returns count)
  • New: delete(entity: E) -> E (instance-based, returns deleted entity)
  • Uses @key attributes to identify entity (same pattern as update())
  • Related: Issue #37

  • Changed EntityManager.delete_many() signature

  • Old: delete_many(**filters) -> int (filter-based with __in support)
  • New: delete_many(entities: list[E]) -> list[E] (instance list, returns list)

  • Changed RelationManager.delete() and delete_many() similarly

  • Uses role players' @key attributes to identify the relation
  • Each role player is matched by their @key attribute

New Features

Instance Delete Methods

  • Added Entity.delete(connection) instance method
  • Delete entity directly: alice.delete(db)
  • Returns self for chaining
  • Location: type_bridge/models/entity.py

  • Added Relation.delete(connection) instance method

  • Delete relation directly: employment.delete(db)
  • Returns self for chaining
  • Location: type_bridge/models/relation.py

Fallback for Entities Without @key

  • Entities without @key can still be deleted if they match exactly 1 record
  • Matches by ALL non-None attributes
  • Raises ValueError if 0 or >1 matches found
  • Provides safer delete behavior than filter-based approach

Migration Guide

# OLD (v0.7.0): Filter-based deletion
deleted_count = manager.delete(name="Alice")  # Returns int

# NEW (v0.7.1): Instance-based deletion
alice = manager.get(name="Alice")[0]
deleted = manager.delete(alice)  # Returns Alice instance

# OR use instance method
alice.delete(db)  # Returns alice

# For filter-based deletion, use filter().delete()
count = manager.filter(name__in=["Alice", "Bob"]).delete()  # Still returns int
count = manager.filter(Age.gt(Age(65))).delete()  # Expression filters

Key Files Modified

  • type_bridge/crud/entity/manager.py - Refactored delete(), delete_many()
  • type_bridge/crud/relation/manager.py - Refactored delete(), delete_many()
  • type_bridge/models/entity.py - Added delete() instance method
  • type_bridge/models/relation.py - Added delete() instance method

[0.7.0] - 2025-12-08

๐Ÿš€ New Features

TransactionContext for Shared Operations

  • Added TransactionContext class for sharing transactions across operations
  • Multiple managers can share a single transaction
  • Auto-commit on context exit, rollback on exception
  • Location: type_bridge/session.py
with db.transaction(TransactionType.WRITE) as tx:
    person_mgr = Person.manager(tx)     # reuses tx
    artifact_mgr = Artifact.manager(tx)  # same tx
    # ... operations commit together

Unified Connection Type

  • Added Connection type alias for flexible connection handling
  • Connection = Database | Transaction | TransactionContext
  • All managers accept any Connection type
  • ConnectionExecutor handles transaction reuse internally
  • Location: type_bridge/session.py

Entity Dict Helpers

  • Added Entity.to_dict() for serialization
  • Unwraps Attribute instances to .value
  • Supports include, exclude, by_alias, exclude_unset options
  • Added Entity.from_dict() for deserialization
  • Optional field_mapping for external key names
  • strict=False mode to ignore unknown fields
  • Location: type_bridge/models/entity.py
person.to_dict()  # {'name': 'Alice', 'age': 30}
Person.from_dict(payload, field_mapping={"display-id": "display_id"})

Django-style Lookup Filters

  • Added lookup suffix operators to filter()
  • __contains, __startswith, __endswith, __regex for strings
  • __gt, __gte, __lt, __lte for comparisons
  • __in for disjunction (multiple values)
  • __isnull for null checks
  • Location: type_bridge/crud/entity/manager.py
person_manager.filter(name__startswith="Al", age__gt=30).execute()
person_manager.filter(status__in=["active", "pending"]).execute()

Bulk Operations

  • Added EntityManager.update_many() - Update multiple entities in one transaction
  • Added EntityManager.delete_many() - Bulk delete with __in filter support

๐Ÿ“š Documentation

  • Comprehensive documentation update
  • Fixed broken example paths in README.md
  • Added Connection types documentation to docs/api/crud.md
  • Added TransactionContext usage examples
  • Added lookup filter documentation with TypeQL mappings
  • Added dict helpers documentation to docs/api/entities.md

๐Ÿ”ง Maintenance

  • Fixed version mismatch between pyproject.toml and init.py
  • Added typings/ stubs for isodate and typedb.driver

๐Ÿ“ฆ Key Files Modified

  • type_bridge/session.py - Added TransactionContext, Connection, ConnectionExecutor
  • type_bridge/models/entity.py - Added to_dict(), from_dict()
  • type_bridge/crud/entity/manager.py - Added lookup filters, update_many, delete_many
  • type_bridge/crud/relation/manager.py - Unified connection handling
  • docs/api/crud.md - New sections for transactions, lookups, bulk ops
  • docs/api/entities.md - Dict helpers documentation

[0.6.4] - 2025-12-04

๐Ÿš€ New Features

CRUD PUT Operations (Idempotent Insert)

  • Added EntityManager.put() for idempotent entity insertion
  • Inserts entity only if it doesn't already exist
  • Safe to call multiple times without creating duplicates
  • Uses TypeQL's PUT clause for atomic match-or-insert semantics
  • Location: type_bridge/crud/entity/manager.py

  • Added EntityManager.put_many() for bulk idempotent insertion

  • All-or-nothing semantics: entire pattern must match or all is inserted
  • Efficient batch operations for data synchronization

  • Added RelationManager.put() for idempotent relation insertion

  • Same PUT semantics for relations with role players
  • Prevents duplicate relationships
  • Location: type_bridge/crud/relation/manager.py

  • Added RelationManager.put_many() for bulk relation PUT

  • Batch idempotent insertion for relations

Use Cases

  • Data import scripts (safe re-runs)
  • Ensuring reference data exists
  • Synchronization with external systems
  • Idempotent API endpoints

๐Ÿ“š Documentation

  • Updated docs/api/crud.md with PUT operations section
  • Comparison table: INSERT vs PUT behavior
  • All-or-nothing semantics explanation
  • Usage examples for entities and relations

  • Added examples/basic/crud_08_put.py tutorial

  • Demonstrates PUT vs INSERT differences
  • Shows idempotent behavior patterns

๐Ÿงช Testing

  • Added entity PUT integration tests (tests/integration/crud/entities/test_put.py)
  • Single put, bulk put_many
  • Idempotency verification
  • All-or-nothing behavior

  • Added relation PUT integration tests (tests/integration/crud/relations/test_put.py)

  • Relation put operations
  • Role player handling

๐Ÿ“ฆ Key Files Modified

  • type_bridge/crud/entity/manager.py - Added put(), put_many()
  • type_bridge/crud/relation/manager.py - Added put(), put_many()
  • docs/api/crud.md - PUT documentation
  • examples/basic/crud_08_put.py - New tutorial
  • tests/integration/crud/entities/test_put.py - Entity PUT tests
  • tests/integration/crud/relations/test_put.py - Relation PUT tests
  • README.md - Updated features

๐Ÿ’ก Usage Examples

# Single PUT (idempotent insert)
alice = Person(name=Name("Alice"), age=Age(30))
person_manager.put(alice)
person_manager.put(alice)  # No duplicate created

# Bulk PUT
persons = [Person(name=Name("Bob")), Person(name=Name("Carol"))]
person_manager.put_many(persons)
person_manager.put_many(persons)  # No duplicates

# Relation PUT
employment = Employment(employee=alice, employer=techcorp)
employment_manager.put(employment)

[0.6.3] - 2025-12-04

๐Ÿš€ New Features

Multi-Player Roles

  • Added Role.multi() for roles playable by multiple entity types
  • Syntax: origin: Role[Document | Email] = Role.multi("origin", Document, Email)
  • Eliminates need for artificial supertype hierarchies
  • Generates multiple plays declarations in TypeQL schema
  • Location: type_bridge/models/role.py
  • Full CRUD support for multi-role relations
  • Filter by specific player type: manager.get(origin=doc)
  • Chainable operations work with multi-roles
  • Batch insert with mixed player types supported
  • Runtime validation: TypeError if wrong player type assigned
  • Pydantic integration: Union types provide IDE/type-checker support

TypeDB 3.7 Compatibility

  • Verified compatibility with TypeDB 3.7.0-rc0
  • Updated documentation to reflect tested TypeDB version

๐Ÿ› Bug Fixes

Inherited Attribute Filter Bug

  • Fixed filters on inherited attributes being silently ignored
  • Root cause: get_owned_attributes() was used instead of get_all_attributes() in filter operations
  • Affected methods: EntityManager.delete(), EntityQuery.delete(), QueryBuilder.match_entity()
  • Example: Dog.manager(db).get(name=LivingName("Buddy")) now works when name is inherited from parent Living class
  • Location: type_bridge/crud/entity/query.py:215, type_bridge/crud/entity/manager.py:219, type_bridge/query.py:193
  • Impact: Dictionary-based filters (get(), delete()) now correctly handle inherited attributes in subtype queries

๐Ÿงช Testing

Multi-Role Tests

  • Multi-role integration tests (tests/integration/crud/relations/test_multi_role.py) - 37 tests
  • Insert relations with different role player types
  • Filter by multi-role players
  • Delete filtered by multi-role
  • Chainable update_with operations
  • Multi-role with 3+ entity types
  • Multi-role unit tests (tests/unit/core/test_multi_role_players.py)
  • Role.multi() API validation
  • Type safety and runtime validation

Inherited Attribute Filter Tests

  • Created unit tests (tests/unit/core/test_inherited_attribute_filter.py) with 9 tests:
  • get_owned_attributes() vs get_all_attributes() behavior verification
  • QueryBuilder.match_entity() with inherited/owned/mixed attribute filters
  • Deep inheritance chain (grandparent โ†’ parent โ†’ child) attribute access
  • Created integration tests (tests/integration/crud/test_inherited_attribute_filter.py) with 5 tests:
  • get() with inherited key attribute
  • delete() with inherited attribute filter
  • Combined inherited + owned attribute filters

๐Ÿ“ฆ Key Files Modified

  • type_bridge/models/role.py - Added Role.multi() and multi-player support
  • type_bridge/schema/info.py - Generate multiple plays declarations
  • type_bridge/crud/relation/manager.py - Multi-role query handling
  • type_bridge/crud/relation/query.py - Multi-role filtering support
  • docs/api/relations.md - Added "Multi-player Roles" documentation
  • type_bridge/crud/entity/query.py - Fixed delete() to use get_all_attributes()
  • type_bridge/crud/entity/manager.py - Fixed delete() to use get_all_attributes()
  • type_bridge/query.py - Fixed match_entity() to use get_all_attributes()
  • tests/integration/crud/relations/test_multi_role.py - New multi-role test suite (37 tests)
  • tests/unit/core/test_multi_role_players.py - New multi-role unit tests

[0.6.0] - 2025-11-24

๐Ÿš€ New Features

Chainable Delete and Update Operations

  • Added EntityQuery.delete() for chainable deletion
  • Delete entities after complex filtering: manager.filter(Age.gt(Age(65))).delete()
  • Builds TypeQL delete query from both dict-based and expression-based filters
  • Single atomic transaction with automatic rollback on error
  • Returns count of deleted entities (0 if no matches)
  • Location: type_bridge/crud.py:626-676

  • Added EntityQuery.update_with(func) for functional bulk updates

  • Update multiple entities using lambda or named functions
  • Example: manager.filter(Age.gt(Age(30))).update_with(lambda p: setattr(p, 'age', Age(p.age.value + 1)))
  • Fetches matching entities, applies function, updates all in single transaction
  • Returns list of updated entities (empty list if no matches)
  • Error handling: Stops immediately and raises error if function fails on any entity
  • All updates in single atomic transaction (all-or-nothing)
  • Location: type_bridge/crud.py:678-730

  • Helper methods added

  • _build_update_query(entity): Builds TypeQL update query for single entity
  • _is_multi_value_attribute(flags): Checks attribute cardinality
  • Reuses existing EntityManager logic for consistency

Benefits

  1. Chainable API: Natural method chaining for complex operations
  2. Type-safe: Full integration with expression-based filtering
  3. Atomic transactions: All operations are all-or-nothing
  4. Functional updates: Clean lambda/function-based bulk updates
  5. Consistent API: Works seamlessly with existing filter() method

AttributeFlags Configuration for Attribute Type Names

  • Added AttributeFlags.name field
  • Explicitly override attribute type name: flags = AttributeFlags(name="person_name")
  • Use case: Interop with existing TypeDB schemas, legacy naming conventions
  • Location: type_bridge/attribute/flags.py:229

  • Added AttributeFlags.case field

  • Apply case formatting to attribute type names: flags = AttributeFlags(case=TypeNameCase.SNAKE_CASE)
  • Supports: CLASS_NAME (default), LOWERCASE, SNAKE_CASE, KEBAB_CASE
  • Use case: Consistent naming conventions across large schemas
  • Location: type_bridge/attribute/flags.py:230

  • Updated Attribute.__init_subclass__ to use AttributeFlags

  • Priority: flags.name > attr_name > flags.case > class.case > default CLASS_NAME
  • Respects both explicit name and case formatting
  • Location: type_bridge/attribute/base.py:108-126

Benefits

  1. Flexible naming: Support for legacy schemas and naming conventions
  2. Consistent API: Mirrors TypeFlags.name pattern for entities/relations
  3. Migration friendly: Easier interop with existing TypeDB databases
  4. Developer choice: Explicit name or automatic case formatting

๐Ÿ—๏ธ Refactoring

Modularized CRUD Operations

  • Refactored monolithic crud.py (3008 lines) into modular structure
  • Split into 11 focused modules under crud/ directory
  • Entity operations: crud/entity/ with manager, query, and group_by modules
  • Relation operations: crud/relation/ with manager, query, and group_by modules
  • Shared utilities: crud/utils.py for format_value and is_multi_value_attribute
  • Base definitions: crud/base.py for type variables
  • Benefits:
  • Eliminated code duplication (shared utilities now have single implementations)
  • Improved maintainability (files are now 200-800 lines each)
  • Better code organization and discoverability
  • Preserved backward compatibility (all imports still work)
  • Impact: No breaking changes, all existing code continues to work

Modularized Models

  • Previously refactored models.py into modular structure
  • Split into models/ directory with base, entity, relation, role, and utils modules
  • Improved separation of concerns and maintainability

๐Ÿ› Bug Fixes

String Attribute Escaping in Multi-Value Attributes

  • Fixed proper escaping of special characters in multi-value string attributes
  • Backslashes are now properly escaped: \ โ†’ \\
  • Double quotes are properly escaped: " โ†’ \"
  • Escape order matters: backslashes first, then quotes
  • Location: type_bridge/query.py, type_bridge/crud.py, type_bridge/models/base.py
  • Impact: Multi-value string attributes with quotes or backslashes now work correctly in insert/update operations
  • Examples:
  • Quotes: Tag('skill "Python"') โ†’ TypeQL: has Tag "skill \"Python\""
  • Backslashes: Path("C:\\Users\\Alice") โ†’ TypeQL: has Path "C:\\Users\\Alice"
  • Mixed: Description(r'Path: "C:\Program Files"') โ†’ TypeQL: has Description "Path: \"C:\\Program Files\""

๐Ÿ“š Documentation

API Documentation Updated

  • Updated docs/api/crud.md with comprehensive new sections:
  • Chainable Delete section with examples and behavior explanation
  • Bulk Update with Function section demonstrating lambda and named function usage
  • Updated EntityQuery method signatures
  • Added "New in v0.6.0" markers for discoverability
  • Error handling and empty results behavior documented

  • Updated docs/api/attributes.md with new section:

  • "Configuring Attribute Type Names" section with comprehensive examples
  • Documents AttributeFlags.name for explicit type name overrides
  • Documents AttributeFlags.case for automatic case formatting
  • Shows priority order and all configuration options
  • Use cases and best practices

  • Updated docs/INTERNALS.md:

  • Updated AttributeFlags dataclass documentation
  • Added name and case fields with usage examples
  • Updated cardinality field names (card_min, card_max)

README Updated

  • Added "Chainable Operations" to features list
  • Highlights filter, delete, and bulk update capabilities
  • Location: README.md

New Example Created

  • Created examples/advanced/crud_07_chainable_operations.py
  • Comprehensive demonstration of chainable delete and update
  • Shows lambda functions, named functions, and complex multi-attribute updates
  • Demonstrates atomic transaction behavior with rollback examples
  • Interactive tutorial format with step-by-step explanations

๐Ÿงช Testing

Integration Tests Added

  • Created tests/integration/crud/entities/test_chainable.py with 9 comprehensive tests:
  • test_chainable_delete_with_expression_filter - Basic delete with expressions
  • test_chainable_delete_with_multiple_filters - Multiple filter combinations
  • test_chainable_delete_returns_zero_for_no_matches - Empty results handling
  • test_chainable_delete_with_range_filter - Range queries (gte/lt)
  • test_update_with_lambda_increments_age - Lambda function updates
  • test_update_with_function_modifies_status - Named function updates
  • test_update_with_returns_empty_list_for_no_matches - Empty results handling
  • test_update_with_complex_function_multiple_attributes - Multi-attribute updates
  • test_update_with_atomic_transaction - Transaction rollback verification

Test Results

  • All 9 tests passing โœ…
  • Tests verify:
  • Correct entity deletion with expression filters
  • Accurate counts returned
  • Proper transaction boundaries (atomic behavior)
  • Error propagation and rollback
  • Empty result handling
  • Multi-attribute updates
  • Lambda and function-based updates

Escaping Test Coverage Added

  • Created comprehensive string escaping test suite
  • 7 unit tests for multi-value string escaping patterns
  • 9 integration tests verifying end-to-end escaping behavior
  • Location: tests/unit/attributes/test_multivalue_escaping.py, tests/integration/crud/attributes/test_multivalue_escaping.py
  • Test coverage includes:
  • Quotes in strings: 'skill "Python"'
  • Backslashes in paths: C:\Users\Alice
  • Mixed escaping: "C:\Program Files\App"
  • Empty strings and special characters
  • Unicode characters (cafรฉ, ๆ—ฅๆœฌ่ชž, emoji๐Ÿ˜€)
  • Single quotes (not escaped in TypeQL)
  • Relations with multi-value escaping
  • Batch operations: insert_many(), update_with()

๐Ÿ“ฆ Key Files Modified

  • type_bridge/crud.py - Added delete() and update_with() to EntityQuery class
  • docs/api/crud.md - Updated API documentation with new methods
  • README.md - Added chainable operations to features list
  • examples/advanced/crud_07_chainable_operations.py - New comprehensive example
  • tests/integration/crud/entities/test_chainable.py - New integration test suite
  • tests/unit/attributes/test_multivalue_escaping.py - New unit test suite (7 tests)
  • tests/integration/crud/attributes/test_multivalue_escaping.py - New integration test suite (9 tests)

๐Ÿ’ก Usage Examples

Chainable Delete

# Delete all persons over 65
count = Person.manager(db).filter(Age.gt(Age(65))).delete()

# Delete with multiple filters
count = manager.filter(
    Age.lt(Age(18)),
    Status.eq(Status("inactive"))
).delete()

Chainable Update with Lambda

# Increment age for all persons over 30
updated = manager.filter(Age.gt(Age(30))).update_with(
    lambda person: setattr(person, 'age', Age(person.age.value + 1))
)

Chainable Update with Function

def promote(person):
    person.status = Status("senior")
    person.salary = Salary(int(person.salary.value * 1.1))

promoted = manager.filter(Age.gte(Age(35))).update_with(promote)

[0.5.1] - 2025-11-20

๐Ÿ› Bug Fixes

Integer Key Query Bug

  • Fixed entities with Integer-type keys failing to query by key value
  • Root cause: Attribute instances not being unwrapped before TypeQL value formatting
  • EntityId(123) was formatted as "123" (string) instead of 123 (integer)
  • Generated incorrect TypeQL: has EntityId "123" causing type mismatch
  • Fix: Added .value extraction in _format_value() before type checking
  • Location: type_bridge/query.py:252-256, type_bridge/crud.py:419-423, type_bridge/crud.py:1145-1149
  • Impact: All non-string attribute types (Integer, Double, Decimal, Boolean, Date, DateTime, DateTimeTZ, Duration) now work correctly as entity keys and in query filters
  • Silent failure fixed: Entities would insert successfully but couldn't be queried, now both work correctly

๐Ÿงช Testing

Regression Tests Added

  • Created comprehensive Integer key test suite
  • 5 new integration tests specifically for Integer key bug regression
  • Tests cover: basic insert/query, comparison with String keys, various integer values, chainable queries, all()/count() methods
  • Location: tests/integration/crud/entities/test_integer_key_bug.py
  • Test Results: 422/422 tests passing (284 unit + 138 integration) โœ…
  • All existing tests still passing
  • All new regression tests passing
  • Zero test failures or regressions

Why String Keys Worked

  • String attributes need quotes in TypeQL anyway
  • Bug accidentally produced correct output: "KEY-123"
  • Integer, Boolean, Double, etc. require unquoted values in TypeQL
  • These would fail with incorrect quoting: "123", "true", "3.14"

๐Ÿ“ฆ Key Files Modified

  • type_bridge/query.py - Fixed _format_value() function
  • type_bridge/crud.py - Fixed EntityManager._format_value() and RelationManager._format_value()
  • tests/integration/crud/entities/test_integer_key_bug.py - New regression test suite (5 tests)

[0.5.0] - 2025-11-20

๐Ÿš€ New Features

Concise Attribute Type-Based Expression API

  • New streamlined query API using attribute class methods
  • Old: Person.age.gt(Age(30)) โ†’ New: Age.gt(Age(30)) โœจ
  • Shorter, more readable syntax with better type checking support
  • Type checkers now correctly validate all expression methods
  • Location: type_bridge/attribute/base.py, type_bridge/attribute/string.py

Class Methods Added to Attribute Base Class

  • Comparison methods: gt(), lt(), gte(), lte(), eq(), neq()
  • Example: Age.gt(Age(30)), Salary.gte(Salary(80000))
  • Aggregation methods: sum(), avg(), max(), min(), median(), std()
  • Example: Salary.avg(), Age.sum()
  • String-specific methods (on String class): contains(), like(), regex()
  • Example: Email.contains(Email("@company.com")), Name.like(Name("^A.*"))

Runtime Validation

  • Automatic attribute ownership validation in filter() methods
  • Validates that entity owns the attribute type being queried
  • Raises ValueError with helpful message if validation fails
  • Example: person_manager.filter(Salary.gt(Salary(50000))) validates Person owns Salary
  • Location: type_bridge/crud.py, type_bridge/expressions/base.py

๐Ÿ”„ API Changes

Expression Classes Refactored

  • Changed from field-based to attribute type-based
  • ComparisonExpr, StringExpr, AggregateExpr now use attr_type instead of field
  • Simpler internal structure with 1-to-1 mapping (attribute type uniquely identifies field)
  • Location: type_bridge/expressions/comparison.py, type_bridge/expressions/string.py, type_bridge/expressions/aggregate.py

Backwards Compatibility

  • Old field-based API still works
  • Person.age.gt(Age(30)) continues to work alongside new API
  • FieldRef classes now delegate to attribute class methods internally
  • Gradual migration path for existing code
  • Location: type_bridge/fields.py

๐Ÿ”ง Type Safety Improvements

Keyword-Only Arguments Enforced

  • Changed @dataclass_transform(kw_only_default=False) โ†’ True
  • All Entity/Relation constructors now require keyword arguments for clarity and safety
  • Improves code readability and prevents positional argument order errors
  • Example: Person(name=Name("Alice"), age=Age(30)) โœ…
  • Positional args now rejected by type checkers: Person(Name("Alice"), Age(30)) โŒ
  • Location: type_bridge/models/base.py:20, type_bridge/models/entity.py:81, type_bridge/models/relation.py:30

Optional Field Defaults Required

  • Added explicit = None defaults for all optional fields
  • Pattern: age: Age | None = None (previously age: Age | None)
  • Makes field optionality explicit in code for better clarity
  • Improves IDE autocomplete and type checking accuracy
  • Required by kw_only_default=True to distinguish optional from required fields
  • Applied throughout codebase: examples, tests, integration tests

Pyright Type Checking Configuration

  • Added pyrightconfig.json for project-wide type checking
  • Excludes validation tests from type checking (tests/unit/type-check-except/)
  • Tests intentionally checking Pydantic validation failures now properly excluded
  • Core library achieves 0 errors, 0 warnings, 0 informations โœจ
  • Proper separation of type-safe code vs runtime validation tests
  • Location: pyrightconfig.json (new file)

Validation Tests Reorganized

  • Moved intentional validation tests to tests/unit/type-check-except/
  • Tests using raw values to verify Pydantic validation now excluded from type checking
  • Original tests fixed to use properly wrapped attribute types
  • Clean separation: type-safe tests vs validation behavior tests
  • Moved files: test_pydantic.py, test_basic.py, test_update_api.py, test_cardinality.py, test_list_default.py

Benefits

  1. Clearer code: Keyword arguments make field names explicit at call sites
  2. Better IDE support: Explicit = None improves autocomplete for optional fields
  3. 100% type safety: Pyright validates correctly with zero false positives
  4. Maintainability: Adding new fields doesn't break existing constructor calls
  5. Error prevention: Type checker catches argument order mistakes at development time

๐Ÿ“š Documentation

Automatic Conversions Documented

  • avg() โ†’ mean in TypeQL
  • TypeDB 3.x uses mean instead of avg
  • User calls Age.avg(), generates mean($age) in TypeQL
  • Result key converted back to avg_age for consistency
  • Clearly documented in docstrings and implementation comments
  • regex() โ†’ like in TypeQL
  • TypeQL uses like for regex pattern matching
  • regex() provided as user-friendly alias
  • Both methods generate identical TypeQL output
  • Documented in method docstrings and code comments

TypeQL Compliance Verification

  • All expressions verified against TypeDB 3.x specification
  • Comparison operators: >, <, >=, <=, ==, != โœ“
  • String operations: contains, like โœ“
  • Aggregations: sum, mean, max, min, median, std, count โœ“
  • Boolean logic: ; (AND), or, not โœ“
  • Created tmp/typeql_verification.md and tmp/automatic_conversions.md

Examples Updated

  • Updated query_expressions.py to use new API
  • All field-based expressions converted to attribute type-based
  • Added notes about API improvements and type safety
  • Location: examples/advanced/query_expressions.py

๐Ÿงช Testing

Test Results

  • 417/417 tests passing (100% pass rate) โœ…
  • Unit tests: 284/284 passing (0.3s)
  • Integration tests: 133/133 passing
  • Type checking: 0 errors, 0 warnings, 0 informations โœ…
  • All type errors eliminated (250 errors โ†’ 0 errors)

Tests Updated

  • Updated field reference tests for new API
  • Tests now check attr_type instead of field attributes
  • All expression creation and TypeQL generation tests passing
  • Location: tests/unit/expressions/test_field_refs.py

Test Organization

  • Integration tests reorganized into subdirectories
  • tests/integration/queries/test_expressions.py - Query expression integration tests
  • tests/integration/crud/relations/test_abstract_roles.py - Abstract role type tests
  • Better organization: crud/, queries/, schema/ subdirectories
  • Improved test discoverability and maintenance

๐Ÿ”ง Type Safety

Type Checking Improvements

  • Eliminated all expression-related type errors
  • Before: 26 errors (.gt(), .avg() "not a known attribute" errors)
  • After: 0 errors โœ…
  • Type checkers now fully understand class method API
  • Pyright passes with 0 errors, 0 warnings, 0 informations

Benefits

  1. Type-safe: Full type checker support with zero errors
  2. Concise: Shorter syntax (Age.gt() vs Person.age.gt())
  3. Validated: Runtime checks prevent invalid queries
  4. Compatible: Old API still works for gradual migration
  5. Documented: All automatic conversions clearly explained

๐Ÿ“ฆ Key Files Modified

  • type_bridge/attribute/base.py - Added class methods for comparisons and aggregations
  • type_bridge/attribute/string.py - Added string-specific class methods
  • type_bridge/expressions/comparison.py - Changed to attr_type-based
  • type_bridge/expressions/string.py - Changed to attr_type-based
  • type_bridge/expressions/aggregate.py - Changed to attr_type-based
  • type_bridge/expressions/base.py - Added get_attribute_types() method
  • type_bridge/expressions/boolean.py - Added recursive attribute type collection
  • type_bridge/fields.py - Updated to delegate to attribute class methods
  • type_bridge/crud.py - Added validation in filter() methods
  • examples/advanced/query_expressions.py - Updated to use new API

[0.4.4] - 2025-11-19

๐Ÿ› Bug Fixes

  • Fixed inherited attributes not included in insert/get operations
  • Entity and Relation insert queries now include all inherited attributes
  • Fetch operations properly extract inherited attribute values
  • Added get_all_attributes() method to collect attributes from entire class hierarchy
  • Location: type_bridge/models/base.py, type_bridge/models/entity.py, type_bridge/crud.py

๐Ÿ”„ API Changes

  • Removed deprecated EntityFlags and RelationFlags aliases
  • Use TypeFlags for both entities and relations
  • All example files updated to use TypeFlags
  • Documentation updated to reflect unified API

๐Ÿ“š Documentation

  • Updated CLAUDE.md: Replaced all EntityFlags/RelationFlags references with TypeFlags
  • Updated examples: All 17 example files now use the unified TypeFlags API

[0.4.0] - 2025-11-15

๐Ÿš€ New Features

Docker Integration for Testing

  • Automated Docker management for integration tests
  • Added docker-compose.yml with TypeDB 3.5.5 server configuration
  • Created test-integration.sh script for automated Docker lifecycle management
  • Docker containers start/stop automatically with test fixtures
  • Location: docker-compose.yml, test-integration.sh, tests/integration/conftest.py
  • Optional Docker usage: Set USE_DOCKER=false to use existing TypeDB server
  • Port configuration: TypeDB server on port 1729

Schema Validation

  • Duplicate attribute type detection
  • Prevents using the same attribute type for multiple fields in an entity/relation
  • Validates during schema generation to catch design errors early
  • Raises SchemaValidationError with detailed field information
  • Location: type_bridge/schema/info.py, type_bridge/schema/exceptions.py
  • Why it matters: TypeDB stores ownership by attribute type, not by field name
  • Using created: TimeStamp and modified: TimeStamp creates a single ownership
  • This causes cardinality constraint violations at runtime
  • Solution: Use distinct types like CreatedStamp and ModifiedStamp

๐Ÿงช Testing

Test Infrastructure

  • Improved test organization: 347 total tests (249 unit + 98 integration)
  • Docker-based integration tests: Automatic container lifecycle management
  • Added duplicate attribute validation tests: 6 new tests for schema validation
  • Location: tests/unit/validation/test_duplicate_attributes.py

๐Ÿ“š Documentation

  • Updated CLAUDE.md:
  • Added Docker setup instructions for integration tests
  • Documented duplicate attribute type validation rules
  • Added schema validation best practices
  • Included examples of correct vs incorrect attribute usage
  • Updated test execution patterns: Docker vs manual TypeDB server options

๐Ÿ”ง CI/CD

  • Updated GitHub Actions workflow:
  • Integrated Docker Compose for automated integration testing
  • Added TypeDB 3.5.5 service container configuration
  • Location: .github/workflows/ (multiple CI updates)

๐Ÿ“ฆ Dependencies

  • Added docker-compose support for development workflow
  • No changes to runtime dependencies

๐Ÿ› Bug Fixes

  • Fixed test fixture ordering: Improved integration test reliability with Docker
  • Enhanced error messages: Schema validation errors now include field names

[0.3.X] - 2025-01-14

โœ… Full TypeDB 3.x Compatibility

Major Achievement: 100% Test Pass Rate (341/341 tests)

Fixed

Query Pagination

  • Fixed TypeQL clause ordering: offset must come BEFORE limit in TypeDB 3.x
  • Changed limit X; offset Y; โ†’ offset Y; limit X;
  • Location: type_bridge/query.py:151-154
  • Added automatic sorting for pagination: TypeDB 3.x requires sorting for reliable offset results
  • Automatically finds and sorts by key attributes when using limit/offset
  • Falls back to required attributes if no key exists
  • Location: type_bridge/crud.py:447-468

Schema Conflict Detection

  • Updated to TypeDB 3.x syntax: Changed from sub to isa for type queries
  • TypeDB 3.x uses $e isa person instead of $e sub entity
  • Fixed has_existing_schema() to properly detect existing types
  • Fixed _type_exists() to use correct TypeQL syntax
  • Location: type_bridge/schema/manager.py:65-284
  • Improved conflict detection: Now properly raises SchemaConflictError when types exist

Type Safety

  • Fixed AttributeFlags attribute access: Changed cardinality_min to card_min
  • Resolved pyright type checking error
  • Location: type_bridge/crud.py:460

Testing

Test Results

  • Unit tests: 243/243 passing (100%) - ~0.3s runtime
  • Integration tests: 98/98 passing (100%) - ~18s runtime
  • Total: 341/341 passing (100%)

Test Coverage

  • All 9 TypeDB attribute types fully tested (Boolean, Date, DateTime, DateTimeTZ, Decimal, Double, Duration, Integer, String)
  • Full CRUD operations for each type (insert, fetch, update, delete)
  • Multi-value attribute operations
  • Query pagination with limit/offset/sort
  • Schema conflict detection and inheritance
  • Reserved word validation

Code Quality

  • โœ… Ruff linting: 0 errors, 0 warnings
  • โœ… Ruff formatting: All 112 files properly formatted
  • โœ… Pyright type checking: 0 errors, 0 warnings, 0 informations

Documentation

  • Updated README.md with current test counts and features
  • Updated CLAUDE.md testing strategy section
  • Added TypeDB 3.x compatibility notes
  • Documented pagination requirements and automatic sorting

Key Files Modified

  • type_bridge/query.py - Fixed clause ordering in build()
  • type_bridge/crud.py - Added automatic sorting for pagination, fixed attribute access
  • type_bridge/schema/manager.py - Updated to TypeDB 3.x isa syntax

[0.2.0] - Previous Release

See git history for earlier changes.