#Operating Boundary Guide

This page is intentionally narrow.

Telepact is a small RPC layer, not a production framework. It does not try to teach general service operations or prescribe one enterprise rollout model. Its job is to make the Telepact boundary explicit so your surrounding service can attach its own auth, logging, metrics, routing, and deployment systems in the right places.

For byte-level wiring, see the Transport Guide.

#1. What Telepact owns

Telepact owns:

• schema-defined request and response shapes

• schema validation

• serialization and deserialization

• binary negotiation

• request / response semantics such as ErrorInvalid* and ErrorUnknown_

• the middleware and hook points around a validated Telepact request

Telepact does not own:

• gateways, meshes, or reverse proxies

• TLS, sockets, and HTTP-specific policy

• service discovery or load balancing

• rate limiting, retries, or circuit breaking

• tracing backends, metrics backends, or log pipelines

• deployment policy, rollout procedure, or incident response process

That split is the main operating model. Keep the Telepact core small, then let your service's own production stack handle the rest.

#2. Where cross-cutting concerns belong

Use this placement guide:

Rule of thumb:

• if it depends on network or transport details, keep it outside Telepact

• if it depends on validated Telepact headers, function names, or Telepact outcomes, Telepact middleware is usually the right cutpoint

• if it depends on domain data or business rules, keep it with the handlers or surrounding service logic

#3. Auth, logging, and metrics

Telepact cares mainly about placement.

#Auth

Telepact's auth convention is:

• define caller-visible credential variants in union.Auth_

• carry them in @auth_

• translate transport-specific credential state into @auth_ at the transport boundary when needed

• use onAuth to normalize authenticated identity into internal headers

• keep authorization decisions near the business logic that owns the resource

The Telepact-specific point is not how your organization should issue tokens or run a gateway. It is that Telepact has one conventional in-band auth shape and one conventional hook point once credentials cross into the Telepact request.

Use the standard auth errors consistently:

• ErrorUnauthenticated_ for missing or invalid credentials

• ErrorUnauthorized_ for authenticated callers who are not allowed to perform the action

For the canonical schema shape and examples, see the Auth Guide.

#Logging and metrics

If you want Telepact-aware logs or metrics, emit them from middleware or hooks that can see:

• the Telepact function name

• normalized caller context

• the response outcome

• elapsed time

Transport logs still answer different questions from Telepact logs. Transport logs describe connections and byte-level behavior; Telepact logs can describe which Telepact function ran and how it completed.

One Telepact-specific pitfall: avoid dumping whole request or response Message objects just because they are available. Even though @auth_ is treated carefully by Telepact, application payloads may still contain sensitive data.

#Request ids and tracing

Telepact can carry correlation data in headers, but it does not define a tracing policy. The important Telepact point is simply to keep the ids consistent across the transport boundary and the Telepact middleware boundary so the same request can be correlated in both places.

#4. Compatibility and upgrades

Telepact provides telepact compare because schema compatibility is part of the Telepact contract surface.

The Telepact-specific guidance is:

• treat checked-in schema as part of the released contract

• compare old and new schema when the contract changes

• keep generated bindings, schema files, and Telepact runtime versions aligned

• stage breaking changes so callers are not forced across incompatible message shapes all at once

For the practical Git-based workflow to compare the checked-in schema on your branch with origin/main or a release tag, see Tooling Workflow: Compare schema versions.

Telepact does not prescribe the surrounding rollout procedure. Whether your organization uses canaries, blue/green, staged regional rollout, or something else is outside this library's scope.

#5. Error boundary notes

Telepact keeps wire behavior and local diagnostics separate:

• schema-invalid messages return ErrorInvalid*

• unexpected handler or serialization failures return ErrorUnknown_ on the wire

• local hooks and exceptions carry the details needed for debugging

That separation is intentional. It keeps the public RPC surface stable while still giving the surrounding service a place to log or inspect failures.

See the Runtime Error Guide for the current local error categories.