feat: typed V2 plan authoring facades for Python and Node

[ds1sqe]

Summary

Ship idiomatic typed plan-authoring facades for Python and TypeScript
over the V2 prepared-query surface. Both bindings can already execute
prepared V2 plans (canonical plan bytes plus invocation JSON through the
native query_v2_runtime modules), but plans themselves can only be
authored in Rust; the cross-binding smoke tests embed Rust-generated
base64 plan fixtures.

Problem

The 2.0.0 contract deliberately scopes plan authoring to Rust: the
upgrade guide states binding facades follow in a later 2.0.x release.
Until they exist, a Python or TypeScript application that wants a new
query shape needs a Rust toolchain to produce the canonical plan bytes,
which undercuts the promise of one semantic engine reachable from every
binding.

Why

This is a multi-flight feature — a new native API surface across two
bindings plus full test matrices — and it no longer blocks 2.0.0: no
released document claims binding-level authoring exists, and no removal
is justified by it. It deserves its own tracked delivery rather than a
tail-end slice of the audit-remediation program.

Proposed change

• Opaque native builder handles. Plan construction happens inside
  the native module through PyO3 / N-API handles; host languages never
  see or assemble serialized plan structure. The existing Rust
  QueryPlan constructors remain the single validation authority.
• Python facade with complete type stubs. A typed builder API in
  type_bridge producing prepared plans that feed the existing
  execute/encode/decode functions unchanged.
• TypeScript facade with generated declarations. The same builder
  shape through N-API, with .d.ts coverage and no never/unsafe
  casts in the public path.
• Authoring test matrices. Representative basic and advanced plans
  (function calls, reduce, try, documents, bounded reachability)
  authored through the public facades in both bindings and executed
  both locally and through the versioned remote envelope against
  released artifacts — no embedded plan bytes anywhere in the suites.
• Docs. The upgrade guide's plan-authoring scoping disclosure is
  replaced by documentation of the shipped surface.

Acceptance criteria

• Python can author every plan shape the canonical vocabulary
  admits through a typed public facade with full stubs
• TypeScript can author the same shapes with generated declarations
  and no unsafe casts in the public path
• The cross-binding smoke suites author their plans through the
  public facades instead of embedded base64 fixtures
• Authored plans execute locally and through the remote envelope
  with outcomes identical to Rust-authored equivalents
• The upgrade guide documents the shipped authoring surface

Related

• Part of epic: Rust-SSOT schema, Query V2, and offline migrations (2.0) #188

[ds1sqe]

Downstream consumer evidence: this facade would let a generated application SDK
expose the same typed fixed-hop query without maintaining a second query AST.

Today, the released @type-bridge/node 1.5.11 direct path works well when the
consumer owns a TypeDB connection:

const q = new QuerySession(connection).registerModels(
  SpecializedItem,
  AlternateItem,
);

const container = q.var(Container);
const edge = q.var(Contains);
const item = q.var(Item, "subtypes");

const rows = q
  .query(container, edge, item)
  .where(
    edge.role(references(Contains).roles.container).connects(container),
    edge.role(references(Contains).roles.item).connects(item),
  )
  .rows({ limit: 50, offset: 0 });

A downstream integration corpus executes this shape against TypeDB 3.12.1. It
returns mixed concrete subtype rows, and a nested traversal materializes the
concrete intermediate subtype rather than collapsing it to its declared base
type. That confirms the typed builder, subtype registration, plan semantics,
and materialization are already suitable for the downstream use case.

The missing downstream seam is remote execution. At the generated application
SDK level, application code should differ only at session acquisition and at
the asynchronous terminal:

const q = remoteContext.querySession().registerModels(
  SpecializedItem,
  AlternateItem,
);

const container = q.var(Container);
const edge = q.var(Contains);
const item = q.var(Item, "subtypes");

const rows = await q
  .query(container, edge, item)
  .where(
    edge.role(references(Contains).roles.container).connects(container),
    edge.role(references(Contains).roles.item).connects(item),
  )
  .rows({ limit: 50, offset: 0 });

The remote context is application-specific and does not need to become a
TypeBridge concept. A generated wrapper can bind scope identity,
authentication, capabilities, limits, and HTTP transport. What it needs from
TypeBridge is a public transport-neutral authoring/execution boundary, for
example a remote session or terminal adapter that:

• uses the same var, query, match, where, ordering, and terminal types
  as the direct facade;
• accepts an already obtained capability advertisement and produces the
  canonical prepared request without exposing mutable plan JSON;
• delegates exactly one request/response exchange when a terminal is awaited,
  with no client-side joins or traversal;
• decodes the remote reply through the same validation and registered model
  constructors as local execution, including concrete subtype hydration;
• preserves structured TypeBridge diagnostics across the transport boundary;
  and
• leaves the existing database-connected QuerySession behavior compatible.

Keeping query construction synchronous and side-effect free, while making only
the remote terminal asynchronous, would be the least surprising downstream
shape. Capability discovery can happen when the remote context is created or be
supplied from a cache, so executing a terminal still remains one opaque query
exchange.

Suggested downstream acceptance case for this issue: author one identical
three-binding subtype query in TypeScript and Python, execute it both locally
and through the remote envelope, and assert the same row ordering, concrete
model classes, and structured failure behavior without casts, embedded plan
bytes, or SDK-specific AST translation.