type-bridge

Treat TypeBridge as a multi-language TypeDB application toolkit. One Rust semantic engine owns schema, query, migration, validation, code generation, ORM, and provider behavior. Python and Node expose language-native facades; generated Rust applications and the query server consume the same contracts.

Choose the surface

| Task | Surface | Read first | | --- | --- | --- | | Build a Python application | type-bridge | getting-started/quickstart.md, guide/models.md, guide/data.md | | Build a Node application | @type-bridge/node | guide/typescript.md | | Build a Rust application | generated schema crate + type-bridge | guide/rust.md | | Own a canonical schema | Split-YAML workspace and CLI | guide/schema-workflows.md, guide/split-yaml-v1.md | | Run remote queries | TypeBridge server | guide/server-container.md, guide/typed-queries.md | | Upgrade an existing app | compatibility guides | guide/upgrade-v2.md, guide/v2-deprecations.md |

Resolve these paths relative to this file when the repository documentation is available. Otherwise use https://ds1sqe.github.io/type-bridge/.

Start every task

1. Determine whether the target is this repository or an application consuming TypeBridge.
2. Inspect the target's pyproject.toml, package.json, Cargo.toml, typebridge.yaml, and schema files as applicable. Do not assume the documentation branch matches the installed version.
3. Identify the language surface, TypeBridge version, TypeDB server version, and whether execution is direct or remote.
4. Identify the canonical V2 Split-YAML workspace. Treat existing TypeQL or released Python/Node declarations as migration input, never as a second active writer for the same scope.
5. Read only the relevant guide pages from the routing table before changing an API boundary.
6. Implement through the language facade and let the Rust engine own semantic validation.
7. Verify the focused behavior, then run the surface-level check.

When working in this repository, read ../DEVELOPMENT.md first. Locate public behavior in these ownership areas:

| Boundary | Source | | --- | --- | | Python facade | ../type_bridge/ | | Shared engines and contracts | ../type-bridge-core/crates/ | | TypeScript/Node facade | ../type-bridge-core/crates/node/ | | Public Rust client | ../type-bridge-core/crates/rust/ | | Schema generation | ../type-bridge-core/crates/schema-codegen/ | | Tests and parity contracts | ../tests/ |

Preserve the contracts

• Keep Rust as the only V2 semantic engine. Do not implement schema, query, migration, validation, or ORM rules independently in Python or TypeScript.
• Use Split-YAML as the sole active desired-schema authority. Read-only archive conversion and released query compatibility are not authoring paths.
• Treat generated Python, TypeScript, and Rust files as projections. Regenerate them after schema changes; do not edit them by hand.
• Sync or migrate the schema before inserting application data.
• Use attribute instances at typed model boundaries.
• Use JavaScript bigint for TypeDB integer values.
• Resolve Rust releases starting with 2.0.1 from crates.io. Resolve historical 2.0.0 consumers from the exact release Git revision.
• Preserve exact compatibility, deprecation, remote-trust, and resource-limit behavior from the relevant guide.

Model TypeDB semantics directly

• Define attributes as reusable independent types. Let entities and relations own them.
• Mark stable identity with Split-YAML key: true and non-key uniqueness with unique: true.
• Express optional and repeated ownership with explicit card bounds.
• Put ordered and distinct on the exact ownership or role edge that carries those semantics.
• Keep relates-side and plays-side cardinalities separate.
• Use abstract schema types and explicit sub edges for polymorphic contracts.
• Treat schema labels as authority; target-language names are generated projections.

Define relation roles and owned attributes in Split-YAML:

format: typebridge.schema/v2
attributes:
  name: { value: string }
  age: { value: integer }
entities:
  person:
    owns:
      name: { key: true }
      age: { card: { min: 0, max: 1 } }
  company:
    owns:
      name: { key: true }
relations:
  employment:
    relates:
      employee: { card: 1 }
      employer: { card: 1 }
plays:
  person:
    employment: { employee: {} }
  company:
    employment: { employer: {} }

Read guide/attributes.md, guide/entities.md, guide/relations.md, and guide/cardinality.md before implementing inheritance, overridden roles, ordered values, schema metadata, or unusual cardinality.

Python workflow

Install Python 3.12–3.14 support:

pip install type-bridge

Generate the Python package from the workspace, apply the canonical migration, then use only generated models and tokens:

from app_models import Age, Name, Person
from type_bridge import Database

db = Database(address="localhost:1729", database="example")
db.connect()
db.create_database()

ada = Person(name=Name("ada"), age=Age(36))
Person.manager(db).put(ada)
adults = Person.manager(db).filter(age__gte=Age(18)).all()

Use keyword arguments for generated entity and relation constructors. Change labels, abstractness, ownership, roles, or cardinalities in Split-YAML and regenerate; do not hand-edit emitted packages.

Use generated model managers for ordinary CRUD, filtering, ordering, grouping, and transactions. Import the generated package's QuerySession for connected multi-model selection, owner-aware fields and roles, named pages, counts, existence checks, bounded reachability, or one-exchange remote execution.

Choose the data operation

| Intent | Operation | | --- | --- | | Create and reject duplicates | insert() / insert_many() | | Idempotently create by key | put() / put_many() | | Persist a known keyed model | update() / update_many() | | Read one model type | manager get, filter, all, first, count | | Match connected model types | immutable QuerySession | | Author binding-neutral V2 plans | type_bridge.query_v2 or Node query-v2 | | Execute handcrafted TypeQL | raw query API, only when typed surfaces do not fit |

Require a key for put() and update(). For relation writes, prefer hydrated role players carrying IIDs; otherwise provide key-complete stubs. Reject role players that have neither identity form.

Reuse a caller-owned transaction for atomic multi-model work:

from type_bridge import TransactionType

with db.transaction(TransactionType.WRITE) as tx:
    Person.manager(tx).put(person)
    Company.manager(tx).put(company)
    Employment.manager(tx).put(employment)

Do not use sync_schema(force=True) as conflict recovery without explicit authorization for database recreation and data loss.

Choose the query surface

• Use manager filters for a single root model, Django-style lookups, aggregation, ordering, pagination, and ordinary CRUD.
• Use the generated Python or TypeScript package's QuerySession for owner-aware, connected, multi-model matches. Create variables from one session and never mix handles or tokens between generated packages.
• Use type_bridge.query_v2 or @type-bridge/node/query-v2 for complete binding-neutral plan authoring. Let Rust create canonical bytes and fingerprints; never assemble mutable plan JSON in a facade.
• Use raw TypeQL only when the higher-level surfaces cannot express the operation, and retain parameterization and version gates.

Treat query construction as local and synchronous. Direct terminals perform provider work. A remote terminal performs exactly one caller-owned exchange; the client owns transport, authentication, retry policy, and capability trust. Generated Python and TypeScript RemoteQuerySession constructors derive authority from private package evidence. Supply advertisement bytes, the one-exchange callback, and limits; never read an authority file or construct a low-level QueryV2Authority for this normal path.

TypeScript and Node workflow

npm install @type-bridge/node

import { Age, Name, Person, QuerySession } from "./generated/app-models/index.js";
import { RustDatabase } from "@type-bridge/node";

const db = RustDatabase.connect("localhost:1729", "example");
const ada = Person.create({ name: Name.create("ada"), age: Age.create(36n) });
Person.manager(db).put(ada);
const adults = Person.manager(db).filter({ age__gte: Age.create(18n) }).all();
const session = new QuerySession(db);

Import immutable model queries from the generated package and low-level V2 plan authoring from @type-bridge/node/query-v2. Consult guide/typescript.md for database lifecycle, integer bigint values, managers, and generation.

Use scheme-free host:port addresses by default. Keep URI scheme and tlsEnabled consistent. Require tlsEnabled: true when supplying tlsRootCa. Close RustDatabase handles when finished, but do not treat synchronous close() as an out-of-band cancellation mechanism for a native call occupying the event-loop thread. Use V2 deadlines for cancellable work.

Canonical schema and generation workflow

For new multi-language systems:

type-bridge --manifest typebridge.yaml schema check
type-bridge --manifest typebridge.yaml schema generate
type-bridge --manifest typebridge.yaml migration make --name initial
type-bridge --manifest typebridge.yaml migration plan
type-bridge --manifest typebridge.yaml migration apply --environment development

Keep credentials in environment references, not committed workspace files. Review a migration plan before applying it. Generation is offline and does not change TypeDB.

Use this lifecycle:

1. Validate the schema set and workspace offline.
2. Generate every configured language package from that checked snapshot.
3. Create a named migration.
4. Review its TypeQL, plan, and destructive classifications.
5. Apply only in an environment whose policy permits migration.
6. Verify the resulting database and journal state.
7. Commit Split-YAML, typebridge.yaml, migrations, and generated packages together when the repository tracks generated outputs.

Treat schema check, migration planning, and generation as read-only with respect to TypeDB. Only the explicit connected migration commands mutate the managed schema. Split-YAML is the sole active authoring authority; historical TOML is a read-only conversion input.

Configure every projection target in typebridge.yaml, then generate them from the same checked workspace. No standalone JSON is required for generated managers or package-owned query sessions.

If deploying the generic server, configure its authority artifact alongside the bindings and commit it with the other generated outputs when the repository tracks them:

artifacts:
  schema-authority:
    output: generated/schema-authority.json

type-bridge --manifest typebridge.yaml schema check
type-bridge --manifest typebridge.yaml schema generate

One generation snapshot embeds compiled authority into every configured package and, when configured, writes the byte-equivalent server artifact. Its canonical JSON is an internal, source-free deployment codec, not a user-maintained schema input.

Rust and server boundaries

Use Rust 1.88 or newer. Bind the generated schema package to the database before using generated models. Follow guide/rust.md for the exact release revision, dependency patch, connection, transaction, CRUD, and remote-query forms.

Classify Rust SDK failures through Error::category(), code(), path(), and model_validation_phase(); do not parse display messages. Preserve those fields across direct and remote execution. In a caller-owned RemoteQueryTransport, wrap transport failures with Error::remote and a stable lowercase snake-case code.

Use the server container only with the configuration, TLS, generated schema_authority_file, explicit authority_mode, resource limits, and immutable digest described in guide/server-container.md. Scope and semantic profile come from the verified artifact rather than duplicate server settings. The client owns remote transport, authentication, retry, and capability-advertisement trust.

Diagnose failures by boundary

| Symptom | Check | | --- | --- | | Connect or protocol failure | TypeDB version, accepted driver band, address, credentials, TLS scheme/options | | Feature rejected before I/O | Feature gate; @doc, @meta, ordered ownership, and given rows can require TypeDB 3.12 | | Schema conflict | Existing types and migration history; do not jump to force recreation | | Missing type during CRUD | Ensure the schema was synchronized or migrated before data operations | | Relation player cannot be matched | Supply a hydrated IID or every key attribute | | Node integer rejected | Use bigint, not JavaScript number | | Generated model mismatch | Regenerate from the canonical schema and compare schema identity/fingerprint | | Typed-query owner/session error | Recreate fields, roles, and variables from the same model owner and session | | Remote reply rejected | Check embedded schema authority, capabilities, executor epoch, signature, deadline, and size limits | | Closed-handle failure | Do not reuse a closed database or transaction; inspect lease ownership |

Read development/typedb.md before changing compatibility or provider behavior. Read development/typed-query-contract.md before changing shared typed-query semantics. Preserve structured diagnostics rather than replacing them with facade-local generic errors.

Verify changes

Select checks by changed surface:

| Change | Minimum verification | | --- | --- | | Python facade or models | focused uv run pytest …, then ./scripts/check.sh python | | Node facade or declarations | focused npm test/typecheck, then ./scripts/check.sh node | | Rust engine or SDK | focused Cargo test, then ./scripts/check.sh rust | | Schema generation | target acceptance test plus Python/TypeScript/Rust projection checks | | Documentation or skill | uv run --extra docs mkdocs build --strict and skill validation | | Cross-surface semantics | parity/contract tests plus ./test.sh when live TypeDB behavior changes |

Use ./test.sh for the full isolated source-tree suite with TypeDB. Exact wheel, npm tarball, native-platform, container, and publication acceptance remains workflow-only.

Before reporting completion:

• confirm generated files and documentation match the implemented surface;
• confirm no compatibility or deprecation promise was broadened accidentally;
• report which source and live tiers ran;
• distinguish local source checks from workflow-only artifact acceptance.