Proto Domain — Technical Specifications

Technical specification for @oshun/proto (libs/proto/): the Protocol Buffer schema library and gRPC runtime helper layer for Oshun inter-service communication. This document catalogs every .proto service definition, every loader/runtime utility, the PROTO_PATHS / SERVICE_NAMES registries, the channel/credential helpers, and the buf toolchain configuration — exactly as they exist in source.

Grounding: every service, RPC, message, enum, function, and registry entry below is taken verbatim from a file under libs/proto/. Where a name in the TypeScript registry disagrees with the .proto source, the discrepancy is flagged explicitly rather than silently reconciled.

@oshun/proto serves two roles simultaneously. First, it is a schema repository: all 28 .proto files describing every gRPC surface in the platform live under libs/proto/src/, organized one directory per domain. Second, it is a runtime helper layer: a small TypeScript surface (loader.ts, services.ts, index.ts) that loads those schemas at startup, exposes typed registries of path keys and service names, and centralizes the channel options and credentials every gRPC client needs.

This document is structured to match how an engineer uses the library. §1–§3 cover the package shape, source layout, and proto conventions. §4–§5 cover the TypeScript API (loader functions and channel helpers). §6–§12 are the authoritative RPC catalog — organized by domain group — derived directly from the .proto source files. §13 documents known discrepancies between the TypeScript registries and the .proto source so consumers know which artifact to trust. §14–§18 cover the Buf toolchain, tests, and the public API surface. §19 is the integration-point summary showing which domain owns which schema area.

1. Package Overview#

@oshun/proto (package.json name, version 0.1.0, private: true) is an Nx library at libs/proto/. It is "type": "module" (pure ESM). It builds with @nx/js:tsc to dist/libs/proto, with main libs/proto/src/index.ts.

The package serves two roles:

1. Schema home — it owns every .proto file describing an Oshun gRPC surface. Twenty-eight .proto files live under libs/proto/src/, organized into one directory per service domain.
2. Runtime helper layer — a small TypeScript surface (loader.ts, services.ts, index.ts) that loads .proto files at runtime via @grpc/proto-loader, exposes typed path/name/metadata registries, and centralizes gRPC channel options and credential construction.

project.json tags the library scope:shared, layer:contracts.

1.1 Build Asset Handling#

The Nx build target (@nx/js:tsc) declares an assets glob that copies **/*.proto from libs/proto/src to protos/ in the build output. The package.json exports map exposes the raw schema files to consumers under the "./protos/*": "./src/*.proto" subpath, alongside the compiled entry point ("." → ./dist/index.js / ./dist/index.d.ts). Proto files are therefore both compiled artifacts' siblings and directly importable as raw schema.

1.2 Dependencies#

From package.json:

typescript catalog: is a peerDependency. The library has no dependency on any other Oshun library — it is a leaf in the dependency graph.

2. Source Layout#

libs/proto/
├── package.json               # @oshun/proto, deps, exports map
├── project.json               # Nx targets: build, lint, test, proto:gen, proto:lint
├── tsconfig.json               # references tsconfig.lib.json + tsconfig.spec.json
├── tsconfig.lib.json           # includes src/**/*.ts + scripts/**/*.ts
├── tsconfig.spec.json          # includes src/**/*.spec.ts + vitest.config.ts
├── vitest.config.ts            # node environment, v8 coverage
├── buf.work.yaml               # buf workspace: directories = [src]
├── buf.gen.yaml                # buf codegen: ts-proto, Go, Go-gRPC, JSON Schema
├── generated/
│   └── buf-image.json          # serialized FileDescriptorSet (buf image, 28 files)
├── scripts/
│   └── generate.ts             # pbjs/pbts static-module type generation script
└── src/
    ├── index.ts               # public API re-exports
    ├── loader.ts              # proto loader + PROTO_PATHS registry
    ├── services.ts            # SERVICE_NAMES, channel options, getServiceMetadata
    ├── proto.spec.ts          # Vitest suite for loader + registries
    ├── buf.yaml               # SINGLE buf module config for the whole src/ tree
    │
    ├── common/types.proto              # oshun.common — shared scalar types
    ├── shared/common.proto             # oshun.shared.common — substrate enums
    ├── shared/evidence.proto           # oshun.shared.evidence — grounded answers
    ├── shared/memory.proto             # oshun.shared.memory — continuity/memory
    ├── shared/persona_policy.proto     # oshun.shared.persona — Lilith policy
    ├── shared/generation_control.proto # oshun.shared.generation — Isis control
    ├── auth/auth.proto                 # oshun.auth
    ├── ai/ai.proto                     # oshun.ai
    ├── agent/agent.proto               # oshun.agent
    ├── asset/asset.proto               # oshun.asset
    ├── collaboration/collaboration.proto # oshun.collaboration
    ├── project/project.proto           # oshun.project
    ├── user/user.proto                 # oshun.user
    ├── isis/isis.proto                 # oshun.isis
    ├── sophia/sophia.proto             # oshun.sophia
    ├── hathor/hathor.proto             # oshun.hathor
    ├── concordia/concordia.proto       # oshun.concordia
    ├── generation3d/generation3d.proto # oshun.generation3d
    ├── rendering/rendering.proto       # oshun.rendering
    ├── splatting/gaussian_splatting.proto # oshun.splatting
    ├── procedural/procedural.proto     # oshun.procedural
    ├── pipeline/autonomous_pipeline.proto # oshun.pipeline
    ├── bridge/blender.proto            # oshun.bridge.blender
    ├── bridge/godot.proto              # oshun.bridge.godot
    ├── bridge/unreal.proto             # oshun.bridge.unreal
    ├── health/health.proto             # oshun.health
    ├── loadbalancing/loadbalancing.proto # oshun.loadbalancing
    ├── reflection/reflection.proto     # oshun.reflection
    └── oshun/v2/persistent_economy/economy.proto # oshun.v2.persistent_economy

Note on buf.yaml placement. There is exactly one buf.yaml, at libs/proto/src/buf.yaml. It is a single buf module that covers the entire src/ subtree — there are no per-domain buf.yaml files. buf.work.yaml at the library root points its directories list at src, so the module root is src/.

3. Proto File Conventions#

Every .proto in the library follows a consistent set of structural conventions. Understanding these conventions upfront makes it easier to read any schema file without surprises about naming, imports, or enum zero values.

Every .proto in the library is syntax = "proto3". Conventions observed across all files:

• Package naming. oshun.<domain> (e.g. oshun.ai, oshun.isis). The shared-substrate files use a two-level suffix: oshun.shared.common, oshun.shared.evidence, oshun.shared.memory, oshun.shared.persona, oshun.shared.generation. The bridge files use oshun.bridge.blender, oshun.bridge.godot, oshun.bridge.unreal. The V2 game file uses oshun.v2.persistent_economy. Packages do not carry a .v1 suffix — buf's PACKAGE_VERSION_SUFFIX lint rule is explicitly disabled (§9.2).
• go_package option. Every file declares option go_package = "github.com/oshun/proto/<path>" — e.g. github.com/oshun/proto/ai, github.com/oshun/proto/shared/evidence, github.com/oshun/proto/v2/persistent_economy.
• No java_package option. Despite what older revisions of this document claimed, no .proto file declares java_package.
• Imports. Files import google/protobuf/timestamp.proto for timestamps, google/protobuf/struct.proto where free-form structured payloads are needed (nine files: agent, collaboration, the three bridges, rendering, and the shared/evidence, shared/memory, shared/generation_control substrate files — rendering.proto declares the import but does not currently reference a Struct field), and google/protobuf/duration.proto (loadbalancing only). Domain files import common/types.proto; the shared-substrate service files additionally import shared/common.proto.
• Enum zero values. Every enum's zero value carries the _UNSPECIFIED suffix (buf enum_zero_value_suffix enforces this) — e.g. AI_PROVIDER_UNSPECIFIED = 0, ISIS_JOB_STATUS_UNSPECIFIED = 0.
• Field naming. snake_case field names. The loader sets keepCase: true, so field names are not camelCased at parse time (§4.1).

4. Loader API (src/loader.ts)#

loader.ts is the runtime bridge between the static .proto files and the live gRPC clients that domain services instantiate at startup. Rather than importing pre-generated JavaScript stubs, services call loadProto (or loadAllProtos at server start), get back a GrpcObject, and read the service constructor out of it by its fully-qualified package path. This approach avoids committing generated code and keeps the .proto files as the single source of truth at both build time and runtime.

loader.ts provides runtime .proto loading on top of @grpc/proto-loader and the PROTO_PATHS registry. It computes its own directory via fileURLToPath(import.meta.url) (pure-ESM pattern).

4.1 DEFAULT_LOADER_OPTIONS#

The shared loader configuration object is used by every loadProto call unless a caller explicitly overrides it. The most consequential option is keepCase: true, which means runtime field names stay snake_case exactly as written in the .proto — they are not camelCased, unlike what buf generate produces via ts-proto (see §14.3 for that divergence).

export const DEFAULT_LOADER_OPTIONS: protoLoader.Options = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
  includeDirs: [__dirname, path.join(__dirname, '..')],
};

keepCase: true is verified by proto.spec.ts (DEFAULT_LOADER_OPTIONS.keepCase toBe true). The two includeDirs entries are the src/ directory itself and its parent (libs/proto/), which is why a domain file's import "common/types.proto" resolves.

4.2 loadProto(protoPath, options?)#

export async function loadProto(
  protoPath: string,
  options?: protoLoader.Options
): Promise<grpc.GrpcObject>;

Loads a single .proto file and returns the gRPC package object (the structure gRPC service constructors are read from). Behavior:

• If protoPath is absolute it is used directly; otherwise it is resolved relative to the src/ directory (path.join(__dirname, protoPath)). This is what lets callers pass a bare PROTO_PATHS value such as 'ai/ai.proto'.
• Options are merged { ...DEFAULT_LOADER_OPTIONS, ...options } — any caller override wins per-key.
• Delegates to protoLoader.load(...) then grpc.loadPackageDefinition(...).
• Asynchronous — returns a Promise<grpc.GrpcObject>.

4.3 loadProtos(protoPaths, options?)#

export async function loadProtos(
  protoPaths: string[],
  options?: protoLoader.Options
): Promise<grpc.GrpcObject>;

Loads several .proto files and merges them into a single GrpcObject. It iterates the array, calls loadProto for each, and Object.assigns each result into a shared merged object. Because the merge is a shallow Object.assign keyed by the top-level package segment (oshun), every file shares the oshun root and later files' subpackages accrete onto it.

4.4 loadAllProtos(options?)#

export async function loadAllProtos(
  options?: protoLoader.Options
): Promise<grpc.GrpcObject>;

Convenience wrapper: loadProtos(Object.values(PROTO_PATHS), options). Loads every file registered in PROTO_PATHS (§4.6) in one call — used where a gRPC server registers all services at startup.

4.5 getProtoPath(relativePath)#

export function getProtoPath(relativePath: string): string;

Joins relativePath onto the src/ directory and returns the absolute path. Unlike loadProto, this is a pure path helper — it does not check existence or load anything.

4.6 PROTO_PATHS Registry#

PROTO_PATHS is an as const object mapping a stable key to a .proto path relative to src/. The exported type ProtoPath is (typeof PROTO_PATHS)[keyof typeof PROTO_PATHS] — the union of the path string literals. Complete contents:

The source file groups these into commented sections: Common types, Core services, Domain services, Shared substrate services, Rendering & 3D, Engine bridges, Infrastructure. proto.spec.ts asserts most of these key→path pairs explicitly.

5. Service Metadata & Channel Helpers (src/services.ts)#

services.ts is the companion to loader.ts. Where loader.ts handles parsing schemas from disk, services.ts centralizes everything needed to construct and configure a gRPC channel: the registry of fully-qualified service names, the shared channel options (keepalive, message-size limits), the credential factory, and per-service metadata. A domain service imports from both modules via the single @oshun/proto entry point.

services.ts exposes the SERVICE_NAMES registry, the DEFAULT_CHANNEL_OPTIONS constant, the createCredentials helper, the ServiceMetadata interface, and the getServiceMetadata lookup.

5.1 SERVICE_NAMES Registry#

SERVICE_NAMES is an as const object mapping a registry key to a fully-qualified gRPC service name. ServiceName is the union of those values. These strings are used when constructing gRPC clients and when calling getServiceMetadata. Note that two entries — Procedural and Reflection — do not match their actual .proto-declared service names; see §13 for the full discrepancy ledger.

Complete contents, grouped as in the source:

Core services

Isis domain (Generative Factory)

Sophia domain (Knowledge Engine)

OSHUN shared substrate services

Concordia domain (Cooperative Mediation & Negotiation)

Hathor domain (Worldbuilding)

V2 game services

Rendering & 3D

Engine bridges

Infrastructure

Two registry entries disagree with the .proto source — do not treat these as authoritative service names:

• SERVICE_NAMES.Procedural is oshun.procedural.ProceduralGenerationService, but procedural/procedural.proto declares service ProceduralGenService. The wire-correct fully-qualified name is oshun.procedural.ProceduralGenService.
• SERVICE_NAMES.Reflection is oshun.reflection.ReflectionService, but reflection/reflection.proto declares service ServerReflectionService. The wire-correct name is oshun.reflection.ServerReflectionService.

See §13 for the full discrepancy ledger.

5.2 DEFAULT_CHANNEL_OPTIONS#

Every gRPC client created by a domain service should use these channel options. The keepalive settings prevent idle HTTP/2 connections from being silently dropped by load balancers, and the 50 MB message-size limits accommodate the largest binary payloads in the system — raw image frames for Gaussian Splatting capture, viewport screenshots from the engine bridges, and inline document content for Sophia ingestion.

export const DEFAULT_CHANNEL_OPTIONS: grpc.ChannelOptions = {
  'grpc.keepalive_time_ms': 30000,
  'grpc.keepalive_timeout_ms': 10000,
  'grpc.keepalive_permit_without_calls': 1,
  'grpc.http2.min_time_between_pings_ms': 10000,
  'grpc.http2.max_pings_without_data': 0,
  'grpc.max_receive_message_length': 50 * 1024 * 1024,
  'grpc.max_send_message_length': 50 * 1024 * 1024,
};

The 50 MB limits and the two keepalive durations are asserted by proto.spec.ts. The 50 MB ceiling accommodates large binary payloads carried in-message — e.g. captured frame bytes on splatting's UploadFrames, viewport bytes on bridge captures, and inline document content on Sophia ingestion.

5.3 createCredentials(...)#

export function createCredentials(
  secure: boolean,
  rootCerts?: Buffer,
  privateKey?: Buffer,
  certChain?: Buffer
): grpc.ChannelCredentials;

Centralized channel-credential factory. Behavior:

• It dynamically require('@grpc/grpc-js') into a local grpcLib binding — an explicit accommodation for ESM/CJS interop, marked with an eslint-disable-next-line @typescript-eslint/no-require-imports.
• If secure is false → grpcLib.credentials.createInsecure().
• If secure is true and both privateKey and certChain are supplied → grpcLib.credentials.createSsl(rootCerts, privateKey, certChain) (mutual TLS with a client certificate).
• If secure is true with no client key/chain → grpcLib.credentials.createSsl(rootCerts) (server-authenticated TLS; rootCerts may itself be undefined, in which case the system trust store is used).

5.4 ServiceMetadata Interface#

export interface ServiceMetadata {
  name: ServiceName; // fully-qualified gRPC service name
  protoPath: string; // .proto path relative to src/
  package: string; // proto package (e.g. 'oshun.ai')
  methods: string[]; // RPC method names
}

5.5 getServiceMetadata(serviceName)#

export function getServiceMetadata(
  serviceName: ServiceName
): ServiceMetadata | undefined;

Returns the ServiceMetadata for a service, or undefined if the name is not in the internal table. The implementation builds a Record<ServiceName, ServiceMetadata> literal keyed by every SERVICE_NAMES value and indexes into it.

The methods arrays in this table are a hand-maintained summary and have drifted from the .proto sources. They are accurate for some services and stale for others. Examples of drift confirmed against source:

• SERVICE_NAMES.AI metadata lists GenerateText, StreamGenerateText, GenerateImage, GenerateAudio, Generate3DModel, GenerateEmbeddings — but ai.proto's AIService actually defines 26 RPCs (§6.3), and never defines an RPC named GenerateAudio returning a result directly nor a bare Generate3DModel matching that signature list.
• SERVICE_NAMES.Agent metadata lists CreateAgent, GetAgent, UpdateAgent, DeleteAgent, ListAgents, RunAgent — but agent.proto's AgentService has no CreateAgent, DeleteAgent, or RunAgent; it has RegisterAgent, DeregisterAgent, AssignTask, etc. (§7.1).
• SERVICE_NAMES.Reflection metadata lists a single method ServerReflectionInfo, which does match the .proto RPC, but is keyed under the non-existent service name oshun.reflection.ReflectionService.

For the authoritative RPC list of any service, use the .proto catalog in §6–§12 of this document, not the getServiceMetadata methods array. The sections below enumerate every RPC directly from source.

6. Common & Core Service Definitions#

Sections §6–§12 are the authoritative RPC catalog for the entire library. Every service, RPC, request type, response type, key message, and enum listed here is taken directly from the .proto source files under libs/proto/src/. Where the TypeScript registry in services.ts disagrees with a .proto declaration, the .proto is correct and the discrepancy is noted in §13.

Each section introduces the service group with context on what problem it solves, followed by the complete RPC table and key message/enum descriptions. The streaming kind notation used throughout is:

• unary — rpc M(Req) returns (Resp)
• server-stream — rpc M(Req) returns (stream Resp)
• client-stream — rpc M(stream Req) returns (Resp)
• bidi-stream — rpc M(stream Req) returns (stream Resp)

This and the following sections (§7–§12) catalog every service, RPC, and message defined in the .proto files. Streaming kind notation:

• unary — rpc M(Req) returns (Resp)
• server-stream — rpc M(Req) returns (stream Resp)
• client-stream — rpc M(stream Req) returns (Resp)
• bidi-stream — rpc M(stream Req) returns (stream Resp)

6.1 common/types.proto — package oshun.common#

common/types.proto is the vocabulary file for the entire library. It defines no service — only the scalar wrapper types, pagination structures, error shapes, and health types that every domain .proto imports. By centralizing these, the library guarantees that a PaginationRequest means the same thing in an auth call as in a rendering call, and that errors are structured consistently across all services.

No service; pure shared types imported by every domain .proto.

Enums: SortOrder (UNSPECIFIED, ASC, DESC); HealthStatus (UNSPECIFIED, HEALTHY, DEGRADED, UNHEALTHY).

Empty, SuccessResponse, UUID, PaginationRequest, PaginationMeta, Error, and SortOrder are the most widely reused: most domain RPCs returning "no payload" return common.SuccessResponse, every list RPC pages with common.PaginationRequest / common.PaginationMeta, and Concordia's stream error frames embed oshun.common.Error.

6.2 auth/auth.proto — AuthService (package oshun.auth)#

AuthService handles both user-facing authentication (login, registration, password reset) and the internal token-validation surface that other services use. The two validation RPCs — ValidateToken and GetTokenClaims — are the key cross-service primitives: a service interceptor can call these to authenticate an incoming gRPC request without any shared session state or HTTP round-trip.

18 RPCs, all unary. Token validation (ValidateToken, GetTokenClaims) is the inter-service-auth surface; the rest are user-facing auth flows.

Key messages: User (id, email, optional username, first_name, last_name, avatar_url, role UserRole, status UserStatus, email_verified, created_at); TokenPair (access_token, refresh_token, access_expires_at, refresh_expires_at, token_type); TokenClaims (user_id, email, role, repeated permissions, issued_at, expires_at, session_id); Session (device/browser/os/ip/location, is_current, created_at, last_active_at); ApiKey (id, name, key_prefix, repeated scopes, timestamps — never carries the raw key). CreateApiKeyResponse carries both the ApiKey and a full_key string (shown once). Enums: UserRole (USER, CREATOR, ADMIN, SUPER_ADMIN), UserStatus (PENDING, ACTIVE, SUSPENDED, DELETED).

6.3 ai/ai.proto — AIService (package oshun.ai)#

AIService is the single cross-provider generation surface: a caller names a provider and model, sends a prompt or media input, and gets back either a streaming response (text, code) or a job handle to poll for completion (images, audio, speech, 3D). This single service abstracts over Anthropic, OpenAI, Google, Stability, ElevenLabs, Replicate, and a local provider, so domain services don't need to implement per-provider clients.

26 RPCs spanning text/image/audio/3D/code generation, embeddings, job management, prompt templates, usage stats, and provider info. Two are server-streaming; the rest are unary.

Enums: AIProvider (ANTHROPIC, OPENAI, GOOGLE, STABILITY, ELEVENLABS, REPLICATE, LOCAL); GenerationType (TEXT, IMAGE, AUDIO, SPEECH, MODEL_3D, CODE, EMBEDDING); JobStatus (PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED); ImageStyle (REALISTIC, ARTISTIC, ANIME, PIXEL_ART, CONCEPT_ART, PHOTOGRAPHIC, DIGITAL_ART).

Notable messages: GenerateTextRequest carries prompt, optional system_prompt, optional provider/model, sampling controls (max_tokens, temperature, top_p, repeated stop_sequences); TextChunk (streamed) has text, is_final, optional usage, finish_reason; TokenUsage (prompt_tokens, completion_tokens, total_tokens); Generate3DModelRequest has a oneof input { string prompt; string image_url }. GenerateJobResponse returns a job_id, status, type, optional estimated_seconds — the async-job pattern: image/audio/speech/3D generation return a job handle, then GetImageResult / GetAudioResult / Get3DModelResult retrieve the finished artifact. Job carries the full job record; UsageStats aggregates total_requests/total_tokens/total_images/total_audio_seconds/ estimated_cost_usd with UsageByType / UsageByProvider / UsageTimeSeries breakdowns.

6.4 agent/agent.proto — see §7.1#

6.5 asset/asset.proto — AssetService (package oshun.asset)#

AssetService manages the lifecycle of binary assets across the platform: 3D models, images, video, audio, documents, and archives. Rather than piping large files through gRPC messages, it uses a two-phase upload pattern: CreateAsset returns a pre-signed storage URL; the client uploads directly to storage; then CompleteUpload records the final metadata. The UpdateProcessingStatus RPC is the internal callback that the processing pipeline uses after it has generated thumbnails and extracted metadata, decoupling the upload from the potentially slow processing step.

23 RPCs, all unary, covering asset CRUD with pre-signed-URL upload, locking, versioning, folders, moves, bulk operations, search, and an internal processing-callback RPC.

CreateAsset is a two-phase upload: the response returns an upload_url, expires_at, and max_size_bytes; the client uploads directly, then calls CompleteUpload. CreateVersion mirrors this for new versions. Asset carries type/status, size, mime, url, Thumbnails (small/medium/large), AssetMetadata (per-type: image dims, video frame rate/codec/bitrate, 3D vertices/faces/materials, audio channels/sample-rate, document pages), version counters, folder/project linkage, and a locked_by/locked_at pair. UpdateProcessingStatus is the internal callback the processing pipeline uses to push status, metadata, and thumbnails back. Enums: AssetType (IMAGE, VIDEO, AUDIO, MODEL_3D, DOCUMENT, SCRIPT, FONT, ARCHIVE, OTHER); AssetStatus (UPLOADING, PROCESSING, READY, ERROR, ARCHIVED); BulkOperation (MOVE, DELETE, ARCHIVE, TAG).

6.6 collaboration/collaboration.proto — CollaborationService (package oshun.collaboration)#

CollaborationService enables real-time multi-user editing sessions. Its design is anchored around SyncDocument, a bidirectional stream that exchanges operational-transform frames in both directions without round-trip overhead — the same technique used by Google Docs. The three server-streams (StreamPresence, StreamCursors, StreamActivity) push peripheral state (who is online, where cursors are, what just happened) as events rather than requiring clients to poll.

32 RPCs. This is the only core service with a bidirectional stream (SyncDocument) plus three server-streams.

SyncDocument carries DocumentUpdate frames both directions — session_id, user_id, version (int64), repeated Operation, timestamp. Operation has type, path, a google.protobuf.Struct value, and optional position/length — the operational-transform unit. Participant carries PresenceStatus, optional CursorPosition (path + offset + anchor + color) and ViewportPosition (scroll x/y + zoom). Enums: SessionType (EDITING, VIEWING, REVIEW, PRESENTATION); SessionStatus (ACTIVE, PAUSED, ENDED); PresenceStatus (ONLINE, AWAY, BUSY, OFFLINE); LockType (EXCLUSIVE, SHARED); ReviewStatus (PENDING, IN_PROGRESS, APPROVED, CHANGES_REQUESTED, REJECTED); ActivityType (JOIN, LEAVE, EDIT, COMMENT, LOCK, UNLOCK, REVIEW, APPROVE, REJECT).

6.7 project/project.proto — ProjectService (package oshun.project)#

ProjectService is the shared project container that creative services build on top of. It provides the membership model (ProjectRole: owner, admin, editor, viewer) and the two internal authorization RPCs — CheckAccess and GetUserRole — that other services call to verify permissions without duplicating membership logic. Any service that gates an action on project membership makes a unary call here rather than querying a shared database.

19 RPCs, all unary: project CRUD (including slug lookup), membership, comments, activity, and two internal authorization-check RPCs.

Project carries name/slug, type/status/visibility, thumbnail/cover URLs, ProjectSettings (default_branch, versioning/comments/time-tracking flags, frame_rate, Resolution, aspect_ratio, color_space), owner, member/asset counts, storage_used_bytes. CheckAccess and GetUserRole are the internal authz surface: CheckAccessResponse returns allowed + optional reason; GetUserRoleResponse returns is_member, optional role, repeated permissions. DeleteProject requires a confirmation string. Enums: ProjectType (FILM, GAME, ANIMATION, COMMERCIAL, MUSIC_VIDEO, OTHER); ProjectStatus (DRAFT, ACTIVE, ON_HOLD, COMPLETED, ARCHIVED); ProjectVisibility (PRIVATE, TEAM, ORGANIZATION, PUBLIC); ProjectRole (OWNER, ADMIN, EDITOR, VIEWER).

6.8 user/user.proto — UserService (package oshun.user)#

UserService owns user profile and identity data. The most important cross-service primitive here is BatchGetUsers: it accepts repeated UUIDs and returns the corresponding User records in a single call, which is how any service that lists items with owner/creator information hydrates the user details without N individual lookups. UserProfile is the public projection (no email, adds social counts) used wherever a user's identity is displayed to other users.

16 RPCs, all unary: profile operations, internal lookups (including BatchGetUsers), preferences, stats, activity, and notifications.

User is the full record; UserProfile is the public projection (no email, adds project/follower/following counts). UserPreferences carries ThemePreference, locale fields, three notification-toggle booleans, a NotificationSettings block (per-event toggles), and EditorSettings (auto_save, auto_save_interval_seconds, vim_mode, font_size, font_family, show_line_numbers). BatchGetUsers takes repeated UUID and returns repeated User — the cross-service user-hydration RPC. Enums: UserRole and UserStatus (same value sets as auth.proto); ThemePreference (LIGHT, DARK, SYSTEM).

7. Agent & Pipeline Service Definitions#

This section covers the two services that model autonomous work orchestration. AgentService handles the lifecycle of individual compute agents — registering them, routing tasks to them, streaming their output, and grouping them into autoscaling pools. AutonomousPipelineService operates at a higher level of abstraction, modeling an entire game or movie production as a project with phases, quality gates, and agent assignments.

7.1 agent/agent.proto — AgentService (package oshun.agent)#

28 RPCs covering agent registration/lifecycle, task management, task I/O streaming, agent pools with autoscaling, inter-agent messaging, and metrics. Two server-streams (StreamTaskOutput, StreamMessages); the rest unary. Imports google/protobuf/struct.proto for free-form task input/output and message payloads.

Agent carries type/status, version, repeated capabilities, AgentConfig (max_concurrent_tasks, task_timeout_seconds, heartbeat_interval_seconds, allowed task types, env map), AgentResources (cpu_cores, memory_bytes, disk_bytes, optional GPU count/memory), optional pool/task linkage. Task carries google.protobuf.Struct input/output, TaskStatus, TaskPriority, parent/child task IDs, required_capabilities, retry counters. HeartbeatRequest reports AgentResourceUsage and current task progress; HeartbeatResponse returns repeated AgentCommand (a type + Struct payload) — the control channel back to the agent. TaskOutput (streamed) carries a stream name + raw bytes data; SendTaskInput pushes raw bytes. Pool + PoolConfig model autoscaling (min_agents, max_agents, target_utilization_percent, scale-up/down thresholds, cooldown_seconds). Enums: AgentType (WORKER, COORDINATOR, SUPERVISOR, SPECIALIST); AgentStatus (REGISTERING, IDLE, BUSY, PAUSED, ERROR, OFFLINE, TERMINATING); TaskStatus (PENDING, ASSIGNED, RUNNING, WAITING, COMPLETED, FAILED, CANCELLED, TIMEOUT); TaskPriority (LOW, NORMAL, HIGH, CRITICAL); ScalingPolicy (FIXED, AUTO, MANUAL).

7.2 pipeline/autonomous_pipeline.proto — AutonomousPipelineService (package oshun.pipeline)#

AutonomousPipelineService is the orchestration surface for fully autonomous game and movie production. A project starts from nothing more than a free-text prompt and a ProjectType; the service then drives it through up to 20 named phases (concept, story, asset creation, VFX, localization, and more), tracking quality gates at each transition and routing work to specialized agents. The two server-streaming RPCs — StreamUpdates and StreamAgentActivity — let a dashboard receive live progress without polling.

43 RPCs. It models end-to-end autonomous game/movie creation: project lifecycle, phase execution, task management, progress streaming, quality gates, agent management, asset tracking, metrics, and templates. Two server-streams (StreamUpdates, StreamAgentActivity); the rest unary. RPC roster by section:

• Project lifecycle (7): CreateProject → ProjectResponse, GetProject, ListProjects → ListProjectsResponse, UpdateProject, CancelProject → common.SuccessResponse, ArchiveProject → common.SuccessResponse, CloneProject → ProjectResponse.
• Phase execution (7): ExecutePhase → PhaseResponse, GetPhase, ListPhases → ListPhasesResponse, SkipPhase → common.SuccessResponse, RetryPhase → PhaseResponse, PausePhase → common.SuccessResponse, ResumePhase → PhaseResponse.
• Task management (7): GetTask → TaskResponse, ListTasks → ListTasksResponse, ExecuteTask, RetryTask, SkipTask → common.SuccessResponse, AddTask, UpdateTaskPriority (the last three → TaskResponse except SkipTask).
• Progress & streaming (4): GetProgress → ProgressResponse, StreamUpdates → stream PipelineUpdate, StreamAgentActivity → stream AgentActivity, GetTimeline → TimelineResponse.
• Quality gates (4): GetQualityGate → QualityGateResponse, ListQualityGates → ListQualityGatesResponse, OverrideQualityGate → common.SuccessResponse, RunQualityCheck → QualityCheckResponse.
• Agent management (4): GetAgentStatus → AgentStatusResponse, ListAgents → ListAgentsResponse, AssignAgent → common.SuccessResponse, GetAgentOutput → AgentOutputResponse.
• Asset tracking (3): ListGeneratedAssets → ListGeneratedAssetsResponse, GetAssetDependencies → AssetDependenciesResponse, ExportAssets → ExportAssetsResponse.
• Metrics & analytics (3): GetMetrics → MetricsResponse, GetCostEstimate → CostEstimateResponse, GetResourceUsage → ResourceUsageResponse.
• Templates & presets (4): ListProjectTemplates → ListProjectTemplatesResponse, GetProjectTemplate → ProjectTemplateResponse, CreateFromTemplate → ProjectResponse, SaveAsTemplate → ProjectTemplateResponse.

CreateProject takes a free-text prompt plus ProjectType and optional ProjectConfig (style, genre, target_platform/audience, quality_level, ConstraintsConfig carrying max_budget, max_tokens, max_gpu_hours, deadline). Enums encode the production model: ProjectType (GAME, MOVIE, SERIES, SHORT_FILM, GAME_EXPANSION, PROTOTYPE); PhaseType — 20 values across pre-production (CONCEPT, STORY, DESIGN, PLANNING), production (ASSET_CREATION, LEVEL_DESIGN, ANIMATION, VFX, AUDIO, PROGRAMMING), post-production (INTEGRATION, TESTING, POLISH, LOCALIZATION, RELEASE), and movie-specific (CINEMATOGRAPHY, EDITING, COLOR_GRADING, SOUND_DESIGN, SCORE); AgentType — 18 values across creative (STORY_DIRECTOR, CHARACTER_WRITER, DIALOGUE_WRITER, WORLD_BUILDER, CONCEPT_ARTIST, CINEMATOGRAPHER), technical (TECHNICAL_DIRECTOR, LEVEL_DESIGNER, ANIMATOR, VFX_ARTIST, SOUND_DESIGNER, COMPOSER), management (PRODUCER, QA_LEAD, LEGAL_CLEARANCE), and specialized (AI_TRAINER, PERFORMANCE_OPTIMIZER, LOCALIZATION_MANAGER); QualityGateType (NARRATIVE_CONSISTENCY, VISUAL_QUALITY, AUDIO_QUALITY, PERFORMANCE, GAMEPLAY, ACCESSIBILITY, LEGAL_COMPLIANCE, TECHNICAL); plus ProjectStatus, PhaseStatus, TaskStatus, TaskPriority, QualityGateStatus, UpdateType. PipelineUpdate (streamed) carries an UpdateType, project/phase/task IDs, a message, and a string map of data.

8. Knowledge & Worldbuilding Service Definitions#

This section covers Sophia (knowledge retrieval and graph) and Hathor (worldbuilding and narrative). Both domains declare multiple services inside a single .proto file, each owning a well-defined slice of the domain. The split means a consumer that only needs search never has to stand up the citation or knowledge-graph service.

8.1 sophia/sophia.proto — Knowledge Engine (package oshun.sophia)#

sophia.proto declares five services. Each service owns one layer of the knowledge stack: SophiaSearchService is the query surface, SophiaDocumentService handles ingest and lifecycle, SophiaCitationService manages attribution, SophiaKnowledgeGraphService manages the structured entity/relation graph, and SophiaIndexService manages the underlying search indexes. Streaming RPCs are noted.

SophiaSearchService — 7 RPCs

SophiaDocumentService — 9 RPCs (IngestDocument, IngestBatch → stream IngestionProgress, GetDocument, UpdateDocument, DeleteDocument → common.SuccessResponse, ListDocuments, GetDocumentChunks, GetIngestionStatus, ListIngestionJobs).

SophiaCitationService — 7 RPCs (CreateCitation, GetCitation, UpdateCitation, DeleteCitation → common.SuccessResponse, ListCitations, VerifyCitation, GetCitationSources).

SophiaKnowledgeGraphService — 16 RPCs: entity ops (CreateEntity, GetEntity, UpdateEntity, DeleteEntity → common.SuccessResponse, ListEntities, MergeEntities), relation ops (CreateRelation, GetRelation, UpdateRelation, DeleteRelation → common.SuccessResponse, ListRelations), graph queries (GetSubgraph, FindPaths, GetNeighbors), and entity resolution (ResolveEntity, SuggestMerges). All unary.

SophiaIndexService — 7 RPCs (CreateIndex, GetIndex, UpdateIndex, DeleteIndex → common.SuccessResponse, ListIndexes, RebuildIndex → stream RebuildProgress, GetIndexStats).

SearchRequest carries query, optional index_id, limit, min_score, repeated SearchFilter (field/operator/value — operator one of eq, ne, gt, lt, gte, lte, in, contains), and include_content/highlight flags. HybridSearchRequest adds semantic_weight/keyword_weight (0.0–1.0, default 0.5 each). FindSimilarRequest uses a oneof target { document_id; chunk_id; text }. IngestDocumentRequest uses a oneof source { url; bytes content; text } and accepts a SophiaChunkingStrategy plus chunk_size/chunk_overlap and a SophiaEmbeddingProvider. SophiaEntity carries aliases, a properties map, and an optional canonical_id (entity-merge linkage). EntityPath (from FindPaths) is a sequence of entity_ids + relation_ids + total_weight. Enums: SophiaDocumentStatus (PENDING, PROCESSING, INDEXED, FAILED, ARCHIVED); SophiaDocumentType (PDF, HTML, MARKDOWN, PLAIN_TEXT, DOCX, EPUB, JSON); SophiaEntityType (PERSON, ORGANIZATION, LOCATION, CONCEPT, EVENT, WORK, CUSTOM); SophiaRelationType (RELATED_TO, PART_OF, INSTANCE_OF, DERIVED_FROM, AUTHOR_OF, LOCATED_IN, OCCURRED_AT, CUSTOM); SophiaChunkingStrategy (FIXED, SEMANTIC, SLIDING_WINDOW, SENTENCE, PARAGRAPH); SophiaEmbeddingProvider (OPENAI, COHERE, LOCAL, HUGGINGFACE).

8.2 hathor/hathor.proto — Worldbuilding & Narrative (package oshun.hathor)#

hathor.proto declares seven services, each owning one dimension of a fictional world: the world container, factions, characters, locations, timeline, narrative quests, and simulation runs. The fine-grained split means a character editor only needs HathorCharacterService, while a procedural-city system can call HathorSimulationService independently. Two RPCs are server-streams (StreamDialogue, StreamSimulation).

HathorWorldService — 12 RPCs: world CRUD (CreateWorld, GetWorld, UpdateWorld, DeleteWorld → common.SuccessResponse, ListWorlds), versioning (CreateWorldVersion, GetWorldVersion, ListWorldVersions, RevertToVersion), export/import (ExportWorld, ImportWorld), and ValidateWorld. All unary.

HathorFactionService — 9 RPCs: faction CRUD (CreateFaction, GetFaction, UpdateFaction, DeleteFaction → common.SuccessResponse, ListFactions), relationships (SetFactionRelation, GetFactionRelations), UpdateFactionResources, GetFactionHistory.

HathorCharacterService — 9 RPCs: character CRUD (CreateCharacter, GetCharacter, UpdateCharacter, DeleteCharacter → common.SuccessResponse, ListCharacters), relationships (SetCharacterRelation, GetCharacterRelations), and dialogue (GenerateDialogue → GenerateDialogueResponse, StreamDialogue → stream DialogueChunk).

HathorLocationService — 9 RPCs: location CRUD (CreateLocation, GetLocation, UpdateLocation, DeleteLocation → common.SuccessResponse, ListLocations), hierarchy (GetLocationHierarchy, MoveLocation), connections (SetLocationConnection, GetLocationConnections).

HathorTimelineService — 11 RPCs: timeline CRUD (CreateTimeline, GetTimeline, UpdateTimeline, DeleteTimeline → common.SuccessResponse, ListTimelines), events (AddEvent, UpdateEvent, DeleteEvent → common.SuccessResponse, GetEvents), event dependencies (SetEventDependency → common.SuccessResponse, GetEventDependencies).

HathorNarrativeService — 12 RPCs: quest CRUD (CreateQuest, GetQuest, UpdateQuest, DeleteQuest → common.SuccessResponse, ListQuests), generation (GenerateQuest, GenerateQuestChain), dialogue trees (CreateDialogueTree, GetDialogueTree, UpdateDialogueTree, ListDialogueTrees), and ValidateNarrative.

HathorSimulationService — 7 RPCs: simulation runs (StartSimulation, StopSimulation → common.SuccessResponse, GetSimulationStatus, ListSimulations), StreamSimulation → stream SimulationUpdate, scenario generation (GenerateScenario, EvaluateScenario).

HathorWorld carries WorldSettings (calendar_system, currency_name, optional magic_system/technology_level) and WorldStats (faction/character/ location/quest/event counts). HathorFaction carries FactionResources (wealth, military_power, political_influence, population as int64, plus a custom-resource int64 map); FactionRelation carries an int32 reputation documented as -100 to 100. HathorCharacter carries CharacterTraits (personality/motivations/flaws/skills/background) and CharacterStats (level, health, attributes map); CharacterRelation carries an int32 affinity (-100 to 100). HathorQuest carries repeated QuestObjective and QuestRewards (experience/currency/items/reputation). DialogueTree is a recursive DialogueNode graph (DialogueChoice references next_node_id). Enums: HathorWorldStatus, HathorFactionType (7 values: NATION, ORGANIZATION, GUILD, TRIBE, CORPORATION, RELIGION, CUSTOM), HathorCharacterRole, HathorLocationType (8 values), HathorQuestType, HathorQuestStatus, HathorSimulationType (ECONOMY, POLITICS, CULTURE, WARFARE, FULL), HathorRelationSentiment (HOSTILE, UNFRIENDLY, NEUTRAL, FRIENDLY, ALLIED).

8.3 isis/isis.proto — Generative Factory (package oshun.isis)#

isis.proto is the internal gRPC surface of the Isis generative factory — the services used by the job queue, worker pool, and tooling that inspects the factory's output. (The product-facing generation-control plane lives in shared/generation_control.proto; these four services are the lower-level execution layer.) isis.proto declares four services. Three RPCs are server-streams (StreamJobProgress, ExportBatch, LoadModel).

IsisJobService — 11 RPCs: job lifecycle (SubmitJob, GetJob, ListJobs, CancelJob → common.SuccessResponse, RetryJob), StreamJobProgress → stream JobProgressUpdate, batch (SubmitBatch, GetBatch), and queue management (GetQueueStats, PauseQueue → common.SuccessResponse, ResumeQueue → common.SuccessResponse).

IsisWorkflowService — 12 RPCs: workflow CRUD (CreateWorkflow, GetWorkflow, UpdateWorkflow, DeleteWorkflow → common.SuccessResponse, ListWorkflows), versioning (CreateWorkflowVersion, GetWorkflowVersion, ListWorkflowVersions, SetActiveVersion), ValidateWorkflow, and templates (ListWorkflowTemplates, ApplyTemplate).

IsisOutputService — 7 RPCs: output retrieval (GetOutput, ListOutputs, DeleteOutput → common.SuccessResponse), provenance (GetProvenance, GetLineage), and export (ExportOutput, ExportBatch → stream ExportProgressUpdate).

IsisModelService — 8 RPCs: model CRUD (RegisterModel, GetModel, UpdateModel, DeleteModel → common.SuccessResponse, ListModels), and status (GetModelStatus, LoadModel → stream ModelLoadProgress, UnloadModel → common.SuccessResponse).

IsisJob carries workflow_id/workflow_version, IsisJobStatus, IsisJobPriority, a parameters string map, repeated IsisOutput, estimated/actual duration in ms, and worker_id. IsisWorkflow carries an IsisWorkflowEngine, an active_version, and optional input/output WorkflowSchema (each a list of typed WorkflowParameter). IsisWorkflowVersion holds the workflow definition as a JSON string. IsisOutput carries IsisOutputType, content_hash, size/mime. ProvenanceInfo records workflow_id/version, parameters, seed, model_ids, worker_version. LineageNode is recursive (ancestors + descendants). Enums: IsisJobStatus (PENDING, QUEUED, PROCESSING, COMPLETED, FAILED, CANCELLED, PAUSED); IsisJobPriority (LOW, NORMAL, HIGH, CRITICAL); IsisWorkflowEngine (COMFYUI, BLENDER, CUSTOM); IsisOutputType (9 values incl. GAUSSIAN_SPLAT, POINT_CLOUD); IsisModelType (CHECKPOINT, LORA, VAE, CONTROLNET, UPSCALER, EMBEDDING, CUSTOM).

9. Concordia Service Definitions#

9.1 concordia/concordia.proto — Cooperative Mediation & Negotiation (package oshun.concordia)#

concordia.proto defines the gRPC contract for live mediation and negotiation sessions. Because parties in a dispute have adversarial interests, the schema enforces a privacy boundary at the protocol level: every RPC that surfaces party-generated content (transcripts, offers, search results) is scoped by a ConcordiaViewerRole, and the services implementing these RPCs MUST apply @concordia/contracts projections before emitting messages. A caucus transcript from Party A can never appear in Party B's stream, and private negotiation strategy is never visible in the shared stream.

Authored for Phase 179.2.2.2. The file header states a hard invariant: every RPC that surfaces party-generated content is scoped by a ConcordiaViewerRole, and services MUST apply the @concordia/contracts projections before emitting any stream message — private artifacts never traverse opposing-party or shared streams. concordia.proto declares three streaming-oriented services.

ConcordiaSessionService — 3 RPCs (live-session transcription)

StreamSessionClientMessage is a oneof kind { SessionStart session_start; AudioFrame audio_frame; SessionCommand command } — the first message MUST be a SessionStart (declaring case_id, participating_party_ids, AudioEncoding, sample_rate_hz, BCP-47 language_tag, enable_co_mediator_suggestions, and pinned_model_versions). AudioFrame carries raw bytes audio plus a monotonic sequence and captured_at. StreamSessionEvent is a oneof kind { TranscriptUpdate; SpeakerDiarizationUpdate; CoMediatorSuggestion; SessionAck; SessionPrivacyNotice; SessionError }. TranscriptUpdate carries a revisable transcript_id/revision, party_id, text, confidence, start/end times, is_final, and a visibility string (a caucus transcript never carries shared_with_all). CoMediatorSuggestion carries an InterventionKind, suggested_wording, rationale, urgency_score (0..1), and a socio_cognitive_label. SessionError embeds oshun.common.Error and a terminal flag. Enums: AudioEncoding (LINEAR16, OPUS, FLAC); InterventionKind (10 values: REFRAME, SUMMARIZE, NAME_INTEREST, REDIRECT_FOCUS, CHECK_UNDERSTANDING, BRAINSTORM_OPTIONS, EMOTIONAL_ACKNOWLEDGMENT, COOL_DOWN_BREAK, SAFETY_ESCALATION, PROPOSE_AGREEMENT_TEST); nested SessionCommand.Kind and SessionPrivacyNotice.Kind.

ConcordiaNegotiationService — 2 RPCs (offer/counter exchange)

NegotiationClientMessage is a oneof kind { NegotiationStart; OfferMessage; CounterMessage; WithdrawMessage; AcceptMessage; NegotiationPing }. OfferMessage references an existing candidate_id or carries inline InlineOfferTerms (each with a JSON-bytes structured_json payload parsed through the @concordia/contracts AgreementDSL). NegotiationEvent is a oneof kind { OfferAccepted; OfferRejected; OfferExpired; CounterProposed; AgreementReached; NegotiationPong; NegotiationNotice }. OfferAccepted carries a nash_product; AgreementReached carries a per_party_utility map (visible only where shared-view projection allows). NegotiationNotice.Kind covers COOLING_OFF_ACTIVE, AUTHORITY_GAP, REVIEWER_REQUIRED, BOUNDARY_BLOCKED, CONSENT_REVOKED, REDLINE_HIT.

ConcordiaSearchService — 2 RPCs (agreement-search progress)

StreamSearchProgressRequest carries case_id, search_run_id, a resume_from_seq for reconnect, and a viewer_role for projection. SearchProgressEvent has an event_seq, emitted_at, and a oneof kind { SearchStarted; SearchIteration; CandidateGenerated; FrontierSnapshot; SearchCompleted; SearchFailed; SearchCancelled; SearchKernelMetric }. SearchStarted records the kernel string (matching the OpenAPI SearchKernel enum), max_iterations, and max_wall_clock_seconds. SearchIteration reports best_nash_product, mean_utility_uncertainty, and redline_violations_pruned. FrontierSnapshot carries viewer-projected Pareto-optimal candidate_ids, total_candidates_evaluated, and a diversity_score. SearchFailed embeds oshun.common.Error.

proto.spec.ts explicitly loads concordia.proto and asserts the three services exist and that getServiceMetadata reports the streaming RPC names (StreamSession/PauseSession/ResumeSession, StreamNegotiation/ SubmitOffer, StreamSearchProgress/CancelSearch). These metadata methods arrays for the three Concordia services are accurate against source.

10. Shared Substrate Service Definitions#

The shared/ directory is architecturally distinct from the domain service files in §6–§9. Domain services (isis/, sophia/, auth/, etc.) are engineering-internal: they implement the platform's infrastructure and are consumed by other backend services. The shared substrate services are product-facing: they are the gRPC surfaces that the OSHUN product domains (Tara, Arete, Veritas, Nyx, Nisaba, and the Assistant shell) call directly. The boundary exists so that product domains always talk to a stable, versioned substrate contract — shared/evidence.proto, shared/memory.proto, etc. — and never depend directly on engineering-internal service internals that might change without notice.

The four shared/*.proto files (plus shared/common.proto) define product-facing substrate contracts — gRPC surfaces consumed by the OSHUN product domains (Tara, Arete, Veritas, Nyx, Nisaba, the Assistant shell). They are distinct from the engineering-internal domain services above.

10.1 shared/common.proto — package oshun.shared.common#

No service. Provides cross-substrate enums and version descriptors: SharedContractCompatibilityMode (BACKWARD_COMPATIBLE, FORWARD_TOLERANT, STRICT, MIXED_ROLLOUT); SharedConsumer (ASSISTANT, TARA, ARETE, VERITAS, NYX, NISABA, ADMIN, STUDIO, SUPPORT); SharedDomain (SHARED, TARA, ARETE, VERITAS, NYX, NISABA); SharedServiceStatus (OK, DEGRADED, UNAVAILABLE). Message SharedContractVersionDescriptor carries contract_id, version, minimum_compatible_version, supported and deprecated version lists, a SharedContractCompatibilityMode, and notes.

10.2 shared/evidence.proto — OshunEvidenceService (package oshun.shared.evidence)#

9 RPCs, all unary — Sophia's product-facing evidence/grounding surface. Imports google/protobuf/struct.proto and shared/common.proto.

GroundedAnswer is the central type: answer text, EvidenceGroundingStatus, confidence, citation trail, EvidenceSourceSummarys, EvidenceClaimChecks, notebooks, an EvidenceSourceGraphPreview, and an embedded EvidencePack. EvidenceItem carries an EvidenceStance (SUPPORTS, CONTRADICTS, CONTEXT, QUOTE, NEUTRAL). Enums: EvidenceSubjectKind (9 values), EvidenceCitationPolicy (REQUIRED, PREFERRED, OPTIONAL), EvidenceGroundingStatus (GROUNDED, PARTIALLY_GROUNDED, UNSUPPORTED, CONFLICTING), EvidenceSearchKind (6 values), EvidenceStance, EvidenceTraceExportKind (BIBLIOGRAPHY, EVIDENCE_TABLE, GROUNDED_REPORT, REVIEW_PACKET), EvidenceTraceExportFormat (JSON, CSV, MARKDOWN, PDF).

10.3 shared/memory.proto — OshunMemoryService (package oshun.shared.memory)#

11 RPCs, all unary — the Iris memory/continuity substrate.

MemoryRecord carries MemoryTier, MemoryScope, importance, access counters, MemoryPrivacyStatus, a SharedDomain, related-memory IDs, a google.protobuf.Struct metadata, and search-ranking fields. PlanWrite returns a MemoryWritePlan evaluating MemoryMode, MemoryStorageTarget, required/missing MemoryConsentTypes, and opt-out blockers before any write. Remember performs the write; Forget (with MemoryDeleteMode SOFT/HARD) deletes. Enums (14 total) include MemoryTier (CORE, WORKING, ARCHIVAL, EPISODIC, SEMANTIC), MemoryScope (7 values), MemoryMode (DURABLE, EPHEMERAL, SUPPRESSED), MemorySearchStrategy (SEMANTIC, KEYWORD, TEMPORAL, HYBRID, ADAPTIVE), MemoryConsentType (13 named values), MemoryLegalBasis (6 GDPR-aligned bases), MemoryStateIndicator, MemoryConsentRollup, MemoryStorageTarget, MemorySearchMatchType, MemoryConsentStatus, MemoryExportFormat.

10.4 shared/persona_policy.proto — OshunPersonaPolicyService (package oshun.shared.persona)#

10 RPCs, all unary — the Lilith persona-policy substrate.

PersonaPolicyPack is the central type: persona/family/category/tradition, ToneGuidance (warmth/formality/pace/directness/complexity, rhetorical devices), core principles, allowed/forbidden topics, disclaimers, a PolicyGroundingRequirement, a PolicyMemoryEnvelope, a VoiceSafetyPolicy, and a PolicyPackStatus. EvaluateInteraction returns a PolicyEvaluationResult bundling selection, SafetyAssessment, TopicScopeResult, tone guidance, a PromptOverlay, and a PolicySafetyDisposition. Enums: PolicyGroundingRequirement (NOT_NEEDED, RECOMMENDED, REQUIRED), PolicyMemoryEnvelope (NONE, SESSION, SCOPED, DURABLE), PolicySafetyDisposition (ALLOW, ALLOW_WITH_DISCLAIMER, REDIRECT, ESCALATE, BLOCK), PolicyRiskLevel (NONE..CRITICAL), PolicyContentCategory, PolicyPackStatus, VoiceSafetyClass (STANDARD, WATERMARKED, CLONE_RESTRICTED, PUBLIC_CLONE_PROHIBITED), VoiceUsageType (PERSONAL, PUBLIC, COMMERCIAL, EDUCATIONAL).

10.5 shared/generation_control.proto — OshunGenerationControlService (package oshun.shared.generation)#

14 RPCs, all unary — the Isis generation-control plane.

PlanGeneration evaluates routing/policy/readiness and returns a GenerationControlPlan (provider family + endpoint, policy bundles, retention policy, a ReleaseReadiness rollup, provenance/watermark/quality-gate flags, estimated cost/duration, blocked reasons). DispatchGeneration actually launches and returns a GenerationExecutionSummary (status, progress, BudgetGuardrailMode, QualityGateMode, output counts). Enums (19 total) include ControlPlaneEnvironment, GenerationJobStatus, GenerationJobPriority, GenerationType (15 named values: TEXT_TO_IMAGE … TEXTURE_UPSCALE), WorkflowEngine, WorkflowVisibility, WorkflowStatus, WorkflowCategory (12 named values), WorkflowPipelineStage, ModelType, ModelFormat (8 named values), ModelCompatibleEngine, ProviderFamily (11 named values), OutputFileType, OutputStatus, StorageTier (HOT, WARM, COLD, GLACIER), ReleaseGateMode, BudgetGuardrailMode, QualityGateMode.

11. Rendering & 3D Service Definitions#

This section covers the four services that form the 3D content creation and rendering pipeline. Generation3DService creates geometry from AI models (text-to-3D, image-to-3D). GaussianSplattingService reconstructs real-world scenes from photo or video capture using Gaussian Splatting and NeRF. ProceduralGenService generates large environments algorithmically via Houdini. RenderingService submits and tracks render jobs across a farm of render nodes. Together these four cover the full pipeline from raw input to finished render.

11.1 generation3d/generation3d.proto — Generation3DService (package oshun.generation3d)#

23 RPCs spanning text-to-3D, image-to-3D, mesh processing, auto-rigging, texture generation, and job management. Three are server-streams (StreamTextToModelProgress, StreamImageToModelProgress, StreamAutoRigProgress — all taking StreamProgressRequest); the rest unary. RPC roster: TextToModel, StreamTextToModelProgress, BatchTextToModel, ImageToModel, MultiViewToModel, StreamImageToModelProgress, OptimizeMesh, GenerateLODs, AnalyzeMesh, UnwrapUVs, CleanupMesh, AutoRig, StreamAutoRigProgress, GenerateWeights, SetupIKFK, GenerateTextures, BakeTextures, GenerateAtlas, GetJob, ListJobs, CancelJob → common.SuccessResponse, RetryJob, GetJobResult. Generation RPCs return GenerationJobResponse (job_id + Job3DStatus + Job3DType + estimated seconds + queue position); mesh RPCs return MeshProcessingResponse; GenerateLODs returns LODGenerationResponse; AnalyzeMesh returns MeshAnalysisResponse; rigging RPCs return RiggingJobResponse; texture RPCs return TextureJobResponse. StreamAutoRigProgress emits RiggingProgress (current_bone, bones_processed/total_bones). Model3DMetadata carries format, poly/vertex/ material counts, texture maps, a BoundingBox, and has_uvs/has_normals/ has_animations/is_rigged flags. Enums: Generation3DProvider (RODIN, MESHY, TRIPO, TRELLIS, HUNYUAN, THREEDFY, LOCAL); OutputFormat3D (GLB, GLTF, FBX, OBJ, USD, USDZ, STL, PLY); QualityPreset (DRAFT, STANDARD, HIGH, ULTRA); Job3DStatus; Job3DType (8 values); SkeletonType (HUMANOID, QUADRUPED, BIRD, CUSTOM); Category3D (11 values).

11.2 rendering/rendering.proto — RenderingService (package oshun.rendering)#

27 RPCs covering render jobs, previews, render farms, render nodes, outputs, presets, and statistics. One server-stream (StreamJobProgress); the rest unary. RPC roster: job ops (SubmitJob, GetJob, CancelJob, RetryJob, ListJobs, StreamJobProgress → stream JobProgress); previews (RequestPreview, GetPreviewStatus); farms (ListFarms, GetFarm, CreateFarm, UpdateFarm, DeleteFarm → common.SuccessResponse); nodes (ListNodes, GetNode, RegisterNode, DeregisterNode → common.SuccessResponse, UpdateNodeStatus); outputs (GetOutput, ListOutputs, DownloadOutput); presets (ListPresets, GetPreset, CreatePreset, UpdatePreset, DeletePreset → common.SuccessResponse); and GetRenderStats. RenderJob carries a RenderEngine, RenderSettings (Resolution, samples, motion blur, denoising, repeated RenderPass, OutputFormat, use_gpu), a FrameRange, and frame counters. JobProgress (streamed) carries frames-completed/total, percent, current frame/node, and a latest FrameResult. RenderNode carries NodeCapabilities (engines, GPU models, OS), NodeResources, and NodeResourceUsage. Enums: RenderEngine (BLENDER_CYCLES, BLENDER_EEVEE, GODOT, UNREAL, ARNOLD, VRAY, OCTANE, REDSHIFT); RenderJobStatus (8 values incl. COMPOSITING); RenderPriority; OutputFormat (8 values incl. MP4, MOV, WEBM, GIF); NodeStatus; FarmType (LOCAL, CLOUD, HYBRID).

11.3 splatting/gaussian_splatting.proto — GaussianSplattingService (package oshun.splatting)#

37 RPCs — the 3D Gaussian Splatting + NeRF pipeline. One client-stream (UploadFrames) and two server-streams (StreamTrainingProgress, StreamRenderProgress); the rest unary. RPC sections:

• Capture (10): StartCapture, ConfigureCamera → common.SuccessResponse, UploadFrames (stream UploadFrameRequest → UploadFramesResponse, client-stream), ProcessVideo, ExtractFrames, AssessFrameQuality, GenerateMasks, EndCapture, GetCaptureSession, ListCaptureSessions.
• Training (9): TrainSplat, StreamTrainingProgress → stream TrainingProgress, GetTrainingMetrics, PauseTraining → common.SuccessResponse, ResumeTraining, CancelTraining → common.SuccessResponse, SaveCheckpoint, LoadCheckpoint, ListCheckpoints.
• NeRF (3): TrainNeRF, ConvertNeRFToSplat, ExportNeRFToMesh.
• Rendering (6): RenderView, RenderViews, RenderVideo, StreamRenderProgress → stream RenderProgress, StartRenderSession, EndRenderSession → common.SuccessResponse.
• Export (5): ExportSplat, ExportForEngine, ExportCompressed, ExportLODs, ExportPointCloud.
• Model management (4): GetSplatModel, ListSplatModels, DeleteSplatModel → common.SuccessResponse, OptimizeSplatModel.

UploadFrameRequest carries raw bytes image_data plus optional camera_id, CameraExtrinsics (flattened 3×3 rotation + translation + intrinsics + distortion), depth_data, and mask_data. TrainingConfig exposes the full 3DGS training surface (iterations, per-attribute learning rates, sh_degree, densification_interval, densify_grad_threshold, max_gaussians). TrainingProgress (streamed) reports current_iteration, loss, psnr/ssim/lpips, and num_gaussians. SplatModelStats records psnr, ssim, lpips, training iterations/seconds. Enums: SplatProvider (3DGS, MIP_SPLATTING, SCAFFOLD_GS, GSGEN, DREAMGAUSSIAN, SUGAR, LOCAL); NeRFProvider (INSTANT_NGP, NERFSTUDIO, MIPNERF360, NERFACTO, TENSORF, PLENOXELS, LOCAL); SplatJobStatus (11 values incl. PREPROCESSING, TRAINING, RENDERING, EXPORTING); CaptureType (SINGLE_CAMERA, MULTI_CAMERA, VIDEO, TURNTABLE, DRONE, HANDHELD); ExportFormat (PLY, SPLAT, KSPLAT, NPZ, UNITY, UNREAL, WEB, POINT_CLOUD); TargetEngine (UNITY, UNREAL, GODOT, WEB, NATIVE).

11.4 procedural/procedural.proto — ProceduralGenService (package oshun.procedural)#

41 RPCs — Houdini-based procedural generation of terrain, cities, biomes, dungeons, space environments, and asset scatter. Four server-streams (StreamTerrainProgress, StreamCityProgress, StreamBiomeProgress, StreamDungeonProgress — all StreamProgressRequest → stream GenerationProgress); the rest unary.

The service is declared service ProceduralGenService. The SERVICE_NAMES.Procedural registry entry (oshun.procedural.ProceduralGenerationService) does not match the source — see §13.

RPC sections: terrain (GenerateTerrain, StreamTerrainProgress, ApplyErosion, GenerateWaterFeatures, GenerateVegetationMask, StitchTerrains, ExportTerrain, PreviewTerrain); city (GenerateCity, StreamCityProgress, GenerateRoadNetwork, GenerateBuildingBlocks, GenerateBuildings, GenerateInfrastructure, ExportCity); biome (GenerateBiome, StreamBiomeProgress, GenerateVegetation, GenerateRocks, GenerateWildlifePaths, ExportBiome); dungeon (GenerateDungeon, StreamDungeonProgress, GenerateConnections, PopulateDungeon, ExportDungeon); space (GenerateStarSystem, GeneratePlanet, GenerateAsteroidField, GenerateNebula, ExportSpaceEnvironment); scatter (ScatterAssets, GenerateInstanceData, ExportScatterData); job management (GetJob, ListJobs, CancelJob → common.SuccessResponse, GetJobResult); template management (ListTemplates, GetTemplate, CreateTemplate). Generation RPCs return ProceduralJobResponse; export RPCs return ExportJobResponse. TerrainConfig carries repeated NoiseLayer (each a NoiseType + amplitude/frequency/octaves/lacunarity/persistence), an ErosionConfig, and a WaterConfig. Enums: ProceduralJobStatus; ProceduralJobType (TERRAIN, CITY, BIOME, DUNGEON, SPACE, SCATTER); NoiseType (PERLIN, SIMPLEX, VALUE, RIDGE, WORLEY, FBM, TURBULENCE, BILLOWY); ErosionType (HYDRAULIC, THERMAL, WIND, COASTAL, GLACIAL); TerrainExportFormat (7 values); BiomeType (12 values); CityStyle (10 values); DungeonStyle (8 values).

12. Engine Bridge & Infrastructure Service Definitions#

This section covers the bridge services (Blender, Godot, Unreal) and the infrastructure services (health, load balancing, reflection, and the V2 game economy). The bridge services all follow the same pattern: an addon or plugin installed inside the DCC application opens a gRPC server, and the platform connects to it using these service definitions to drive the application programmatically. The infrastructure services (health, load balancing, reflection) are standard gRPC ecosystem patterns rather than domain-specific schemas.

12.1 bridge/blender.proto — BlenderBridgeService (package oshun.bridge.blender)#

32 RPCs — a control surface over a running Blender instance via a Blender addon. Three server-streams (RenderSequence → stream RenderProgress, StreamExecuteScript → stream ScriptOutput, StreamEvents → stream BlenderEvent); the rest unary. RPC sections: connection (Connect, Disconnect → common.SuccessResponse, GetStatus, Heartbeat); scene (GetScene, CreateScene, SaveScene → common.SuccessResponse, LoadScene); object (ListObjects, GetObject, CreateObject, UpdateObject, DeleteObject → common.SuccessResponse, DuplicateObject); material (ListMaterials, GetMaterial, CreateMaterial, UpdateMaterial, AssignMaterial → common.SuccessResponse); animation (GetAnimation, SetKeyframe → common.SuccessResponse, PlayAnimation → common.SuccessResponse, StopAnimation → common.SuccessResponse); rendering (RenderFrame, RenderSequence, GetRenderSettings, UpdateRenderSettings); Python execution (ExecuteScript, StreamExecuteScript); asset I/O (ImportAsset, ExportAsset); and StreamEvents. BlenderObject carries an ObjectType and a Transform (Vector3 location/rotation/scale). SetKeyframe carries a google.protobuf.Struct value. Enum: ObjectType (MESH, CURVE, SURFACE, ARMATURE, EMPTY, CAMERA, LIGHT, SPEAKER, VOLUME).

12.2 bridge/godot.proto — GodotBridgeService (package oshun.bridge.godot)#

28 RPCs — a control surface over a running Godot editor. Three server-streams (StreamSignals → stream SignalEvent, ExportProject → stream ExportProgress, StreamEvents → stream GodotEvent); the rest unary. RPC sections: connection (Connect, Disconnect → common.SuccessResponse, GetStatus); project (GetProject, OpenScene, SaveScene → common.SuccessResponse, ReloadScene); scene tree (GetSceneTree, GetNode, CreateNode, UpdateNode, DeleteNode → common.SuccessResponse, ReparentNode, DuplicateNode); resources (GetResource, CreateResource, SaveResource → common.SuccessResponse, ListResources); scripts (GetScript, UpdateScript, ExecuteMethod); signals (EmitSignal → common.SuccessResponse, ConnectSignal → common.SuccessResponse, StreamSignals); editor ops (RunProject, StopProject → common.SuccessResponse, ExportProject); and StreamEvents. GodotNode carries Transform2D and Transform3D and a map<string, google.protobuf.Value> of properties; ExecuteMethod and EmitSignal pass repeated google.protobuf.Value arguments. No enums.

12.3 bridge/unreal.proto — UnrealBridgeService (package oshun.bridge.unreal)#

56 RPCs — the largest service in the library, a control surface over a running Unreal Engine editor. Four server-streams (BuildProject → stream BuildProgress, RenderSequence → stream RenderProgress, StreamEvents → stream UnrealEvent, StreamLogs → stream LogEntry); the rest unary. RPC sections: connection (Connect, Disconnect, GetStatus, Heartbeat); project (GetProject, OpenProject, SaveProject → common.SuccessResponse, BuildProject); level (ListLevels, GetLevel, OpenLevel, SaveLevel → common.SuccessResponse, CreateLevel); actor (ListActors, GetActor, SpawnActor, UpdateActor, DestroyActor → common.SuccessResponse, DuplicateActor); component (ListComponents, GetComponent, AddComponent, UpdateComponent, RemoveComponent → common.SuccessResponse); blueprint (ListBlueprints, GetBlueprint, CreateBlueprint, CompileBlueprint, GetBlueprintGraph); material (ListMaterials, GetMaterial, CreateMaterial, UpdateMaterial, AssignMaterial → common.SuccessResponse); animation (ListAnimations, GetAnimation, PlayAnimation → common.SuccessResponse, StopAnimation → common.SuccessResponse, GetSequencer, ControlSequencer); asset (ListAssets, GetAsset, ImportAsset, ExportAsset, ReimportAsset); rendering (CaptureViewport, RenderSequence, GetRenderSettings, UpdateRenderSettings); Play-In-Editor (StartPIE, StopPIE → common.SuccessResponse, GetPIEStatus); console (ExecuteConsoleCommand, ExecutePython); and StreamEvents / StreamLogs. UnrealActor carries a Transform (Vector3 location/scale + Rotator pitch/yaw/roll). Enums: EngineMode (EDITOR, PIE, STANDALONE, SERVER); BlueprintType; MaterialDomain (6 values); BlendMode (OPAQUE, MASKED, TRANSLUCENT, ADDITIVE, MODULATE); ShadingModel (11 values); AnimationType; SequencerCommand; ImageFormat (PNG, JPEG, EXR, BMP); PIEMode (6 values); LogVerbosity (8 values).

12.4 health/health.proto — HealthService (package oshun.health)#

The gRPC standard health-checking pattern. Two RPCs:

HealthCheckRequest carries a service string (empty = overall server health). HealthCheckResponse carries a ServingStatus enum (SERVING_STATUS_UNKNOWN, SERVING_STATUS_SERVING, SERVING_STATUS_NOT_SERVING, SERVING_STATUS_SERVICE_UNKNOWN). The file comments note SERVICE_UNKNOWN is only used for Watch; Check returns a NOT_FOUND gRPC status instead. This is a distinct definition from common/types.proto's HealthCheckRequest/HealthCheckResponse pair (which carries a richer HealthStatus and ServiceCheck list, §6.1) — the two are not the same message.

12.5 loadbalancing/loadbalancing.proto — LoadBalancingService (package oshun.loadbalancing)#

5 RPCs. One server-stream (WatchEndpoints); the rest unary.

Imports google/protobuf/duration.proto. Endpoint carries host/port, EndpointHealth, weight, priority, a Locality (region/zone/sub-zone), and a metadata map. LoadBalancingPolicy aggregates a LoadBalancingStrategy, a HealthCheckConfig, a RetryPolicy (max retries, exponential backoff via backoff_multiplier, retryable status codes), a CircuitBreakerConfig, an OutlierDetectionConfig, a RingHashConfig, and a LocalityConfig. ReportHealthRequest carries LatencyStats (p50/p90/p99/avg). Enums: LoadBalancingStrategy (ROUND_ROBIN, WEIGHTED_ROUND_ROBIN, PICK_FIRST, LEAST_CONNECTIONS, RANDOM, RING_HASH, LOCALITY_AWARE); EndpointHealth (HEALTHY, UNHEALTHY, DEGRADED, DRAINING); UpdateType (ADDED, MODIFIED, REMOVED).

12.6 reflection/reflection.proto — ServerReflectionService (package oshun.reflection)#

The gRPC standard server-reflection pattern. One RPC:

The service is declared service ServerReflectionService. The SERVICE_NAMES.Reflection registry entry (oshun.reflection.ReflectionService) does not match — see §13.

ServerReflectionRequest carries a host and a oneof message_request (file_by_filename, file_containing_symbol, file_containing_extension → ExtensionRequest, all_extension_numbers_of_type, list_services). ServerReflectionResponse carries a oneof message_response (FileDescriptorResponse with serialized FileDescriptorProto bytes, ExtensionNumberResponse, ListServiceResponse, ErrorResponse). This is the schema for the standard reflection protocol that lets tools like grpcurl discover services on a running server.

12.7 oshun/v2/persistent_economy/economy.proto — package oshun.v2.persistent_economy#

A single file declaring three small services for Section-130 open-world game systems. All RPCs unary.

Economy — 3 RPCs: GetShopInventory (GetShopInventoryRequest → ShopInventory), GetPriceCurve (GetPriceCurveRequest → PriceCurve), RecordTransaction (RecordTransactionRequest → TransactionAck).

NPCSchedule — 1 RPC: GetActiveSchedule (GetActiveScheduleRequest → ActiveSchedule).

CrimeRate — 1 RPC: GetDistrictRate (GetDistrictRateRequest → DistrictCrimeRate).

ShopInventory carries a daily_seed and weekly_vehicle_part_seed (shared across all players for fairness) plus repeated ShopInventoryItem (price_minor as int64, demand_priced, premium_shop_migration). PriceCurve carries demand_percentile/supply_percentile, a price_multiplier, and an event_topic. RecordTransactionRequest carries an account_id and an ip_rate_bucket for anti-bot rate caps; TransactionAck returns accepted, anti_bot_flagged, and an event_topic. ActiveSchedule carries repeated NPCScheduleRow (routine block, district, interaction, behavior_intent). DistrictCrimeRate carries crime_rate_percent (0–100), cop_spawn_density, and a lockdown_active flag. This file has no enums — all discriminators are strings. proto.spec.ts loads it and asserts the three services (Economy, NPCSchedule, CrimeRate) exist.

13. Registry / Source Discrepancy Ledger#

The TypeScript registries in services.ts are hand-maintained. Over time they have drifted from the .proto sources in three classes of ways. This section is a complete ledger of known discrepancies so consumers always know which artifact is authoritative. The short answer: for any service name or RPC method list, trust the .proto file, not the registry value.

The TypeScript registries in services.ts are hand-maintained and have drifted from the .proto sources in three classes of way. These are documented here so consumers know which artifact is authoritative.

A. Service-name mismatches (the registry value is not the wire name).

A gRPC client constructed by reading the package object from loadProto will find the service at the .proto-declared name, not the SERVICE_NAMES value.

B. getServiceMetadata methods arrays are partial / stale. The methods array on each ServiceMetadata is a hand-written subset that has not tracked .proto changes. Examples confirmed against source: AI metadata names a GenerateAudio/Generate3DModel/GenerateEmbeddings shortlist that does not match the 26 actual AIService RPCs; Agent metadata names CreateAgent/DeleteAgent/RunAgent, none of which exist (the real RPCs are RegisterAgent/DeregisterAgent/AssignTask/etc.); Asset, Project, User, Generation3D, Rendering, GaussianSplatting, Procedural, Pipeline, LoadBalancing metadata arrays are likewise partial. The Concordia and shared- substrate metadata arrays are accurate. §6–§12 of this document, derived directly from the .proto files, are authoritative for RPC rosters.

C. The metadata table has no entry for every service. getServiceMetadata covers the services keyed in SERVICE_NAMES, but where a single .proto file declares several services (Isis: 4, Sophia: 5, Hathor: 7, Concordia: 3) each is a separate SERVICE_NAMES key with its own metadata record.

These are factual observations about the current code, not defects this document is empowered to fix (the assignment scope is the two DOMAINS/proto docs only). They are recorded so the spec does not silently launder the drift.

14. Buf Toolchain Configuration#

@oshun/proto uses buf to manage the proto lifecycle. Buf replaces raw protoc invocations with a declarative, reproducible pipeline: a workspace file declares where the module root is, a module config declares lint rules and external dependencies, and a generation config declares exactly which plugins run and where they write output. This means any engineer can run buf lint and buf generate and get the same result without installing separate plugin binaries.

@oshun/proto uses buf for proto linting, breaking-change detection, and code generation. Three buf files exist.

14.1 buf.work.yaml (library root)#

version: v1
directories:
  - src

Declares the buf workspace. The single workspace directory is src, so the module root is libs/proto/src/ and all imports resolve relative to it (which is why import "common/types.proto" works).

14.2 src/buf.yaml (single module config)#

version: v1
name: buf.build/oshun/proto
lint:
  use:
    - DEFAULT
    - COMMENTS
  except:
    - PACKAGE_VERSION_SUFFIX
    - SERVICE_SUFFIX
    - RPC_REQUEST_RESPONSE_UNIQUE
    - RPC_REQUEST_STANDARD_NAME
    - RPC_RESPONSE_STANDARD_NAME
  enum_zero_value_suffix: _UNSPECIFIED
  rpc_allow_same_request_response: false
  rpc_allow_google_protobuf_empty_requests: true
  rpc_allow_google_protobuf_empty_responses: true
  allow_comment_ignores: true
breaking:
  use:
    - FILE
  except:
    - FIELD_SAME_JSON_NAME
    - ENUM_VALUE_NO_DELETE
deps:
  - buf.build/googleapis/googleapis

There is exactly one buf.yaml, at src/buf.yaml. It declares the buf module buf.build/oshun/proto and covers the entire src/ tree — there are no per-domain buf.yaml files.

• Lint. Uses the DEFAULT rule group plus COMMENTS (every public API element must be documented — this is why every service/RPC/message in the library carries a doc comment). Five rules are disabled: PACKAGE_VERSION_SUFFIX (so packages can be oshun.ai, not oshun.ai.v1), SERVICE_SUFFIX (the Service suffix is used by convention but not enforced), and three RPC request/response naming rules (RPC_REQUEST_RESPONSE_UNIQUE, RPC_REQUEST_STANDARD_NAME, RPC_RESPONSE_STANDARD_NAME) — which is why many RPCs legitimately share request types (e.g. GetGenerationResultRequest is reused by three AI RPCs; GetUserRequest by five User RPCs). enum_zero_value_suffix is set to _UNSPECIFIED. rpc_allow_same_request_response: false still forbids an RPC using the same type for request and response. rpc_allow_google_protobuf_ empty_requests/_responses: true permits — though the library actually uses its own oshun.common.Empty, not google.protobuf.Empty. allow_comment_ignores: true lets a // buf:lint:ignore comment suppress a rule locally.
• Breaking. Uses the FILE rule group (file-level breaking-change detection) with two exceptions: FIELD_SAME_JSON_NAME and ENUM_VALUE_NO_DELETE.
• Deps. Declares one external module dependency: buf.build/googleapis/googleapis (for the well-known google.protobuf.* imports).

14.3 buf.gen.yaml (library root) — Code Generation#

version: v1
managed:
  enabled: true
  go_package_prefix:
    default: github.com/oshun/proto/gen/go
plugins:
  - plugin: buf.build/community/stephenh-ts-proto
    out: gen/ts
    opt:
      [
        esModuleInterop=true,
        outputServices=grpc-js,
        env=node,
        useOptionals=messages,
        exportCommonSymbols=false,
        snakeToCamel=true,
        stringEnums=true,
        forceLong=long,
        outputTypeRegistry=true,
        useDate=true,
      ]
  - plugin: buf.build/protocolbuffers/go
    out: gen/go
    opt: [paths=source_relative]
  - plugin: buf.build/grpc/go
    out: gen/go
    opt: [paths=source_relative]
  - plugin: buf.build/community/chrusty-protoc-gen-jsonschema
    out: gen/jsonschema
    opt:
      [
        all_fields_required,
        disallow_additional_properties,
        disallow_bigints_as_strings,
        enforce_oneof,
        file_extension=.schema.json,
      ]

buf generate runs four remote plugins. Managed mode is enabled with a go_package_prefix of github.com/oshun/proto/gen/go.

The ts-proto plugin is the TypeScript generator (it replaces the older grpc-web setup that earlier revisions of this document described). Its options configure: outputServices=grpc-js (server/client stubs target @grpc/grpc-js, matching the runtime dependency), env=node, useOptionals=messages (proto3 optional fields become TS optional properties), snakeToCamel=true (the generated TS does camelCase field names — note this differs from the runtime loader's keepCase: true), stringEnums=true (enums as string-literal unions), forceLong=long (64-bit ints as long objects), outputTypeRegistry=true, and useDate=true (google.protobuf.Timestamp ↔ JS Date). Output directories (gen/ts, gen/go, gen/jsonschema) are relative to libs/proto/.

14.4 The generated/ Directory#

libs/proto/generated/ contains a single committed artifact: buf-image.json (~2 MB) — a serialized buf image (a FileDescriptorSet in JSON form). It contains all 28 .proto files of the module as FileDescriptorProto entries, 26 of which contain at least one service. A buf image is the self-contained input buf consumes for breaking-change comparison and code generation; it is the compiled, dependency-resolved form of the schema. The gen/ts, gen/go, and gen/jsonschema output directories named in buf.gen.yaml are not committed under generated/ — they are produced on demand by buf generate.

14.5 scripts/generate.ts#

scripts/generate.ts is an alternative, protobufjs-based type generator, separate from the buf toolchain. It is a tsx-executable ESM script that:

1. Recursively finds every .proto under src/ (findProtoFiles).
2. Ensures generated/ exists.
3. Locates the pbjs and pbts binaries under node_modules/.bin/; if either is absent it logs a skip notice and returns (no failure).
4. Runs pbjs -t static-module -w es6 to emit generated/proto.js.
5. Runs pbts to emit generated/proto.d.ts from that JS.

This produces a single static-module pair (proto.js + proto.d.ts) covering all schemas. It coexists with — and is independent of — the buf generate pipeline; the two are different generation paths and emit to different targets.

14.6 Nx Targets#

project.json defines five Nx targets:

proto:gen and proto:lint invoke buf directly. There is no Nx target wired to buf breaking — breaking-change checks are run manually or in CI against the FILE rule group declared in src/buf.yaml.

15. Tests (src/proto.spec.ts)#

The Vitest test suite validates that the TypeScript helper layer is correctly wired to the .proto files. Because this library has no domain logic — only schema and helpers — the tests focus entirely on confirming that registries map to the right values, the loader can parse real schema files, and the channel constants have the expected numeric values. The suite also serves as a regression gate: if someone renames a service in a .proto file without updating a registry, the test that calls loadProto and reads the service constructor will fail.

The Vitest suite proto.spec.ts exercises the loader and registries. It does not test domain logic (there is none in this library — it is schema + helpers). Coverage:

• PROTO_PATHS — asserts ~22 key→path pairs (common, ai, asset, auth, project, user, collaboration, the five shared* keys, generation3d, rendering, splatting, persistentEconomy, blender, godot, unreal, health, loadbalancing, pipeline, and concordia).
• SERVICE_NAMES — asserts core, shared-substrate, 3D/rendering, V2, bridge, and infrastructure service names match their expected literals.
• DEFAULT_CHANNEL_OPTIONS — asserts the two keepalive durations (30000, 10000) and both 50 MB message-size limits.
• DEFAULT_LOADER_OPTIONS — asserts keepCase: true, longs: String, enums: String, defaults: true, oneofs: true.
• getServiceMetadata — asserts metadata is returned for AI, Asset, Auth, the three bridges, the four shared-substrate services, the three V2 services, and the three Concordia services, and spot-checks selected method names.
• loadProto — actually parses shared/evidence.proto, shared/memory.proto, shared/persona_policy.proto, shared/generation_control.proto, concordia/concordia.proto, and oshun/v2/persistent_economy/economy.proto, asserting the expected package objects and service constructors are present. The Concordia and V2 cases drill into pkg.oshun.concordia.ConcordiaSessionService etc. and pkg.oshun.v2.persistent_economy.Economy etc.
• Concordia metadata — a dedicated block asserts PROTO_PATHS.concordia, the three SERVICE_NAMES.Concordia* values, and the streaming method names on each Concordia service's metadata.

vitest.config.ts runs in the node environment with globals: true and v8 coverage (text, json, html reporters).

16. Public API (src/index.ts)#

index.ts is the single entry point for @oshun/proto. It re-exports everything a consuming service needs in one import: the loader functions and path registry from loader.ts, the service name registry and channel helpers from services.ts, and a set of @grpc/grpc-js types re-exported for consumer convenience — so that a domain service that only uses @oshun/proto as a dependency does not also need to depend directly on @grpc/grpc-js for type-only use.

index.ts is the package entry point. It re-exports:

From ./loader: loadProto, loadProtos, loadAllProtos, getProtoPath, DEFAULT_LOADER_OPTIONS, PROTO_PATHS, and the type ProtoPath.

From ./services: SERVICE_NAMES, DEFAULT_CHANNEL_OPTIONS, createCredentials, getServiceMetadata, and the types ServiceName and ServiceMetadata.

Re-exported @grpc/grpc-js types (for consumer convenience, so a domain service need not depend on @grpc/grpc-js directly for type-only use): Client, Server, ServiceDefinition, MethodDefinition, GrpcObject, ChannelCredentials, ChannelOptions, Metadata, ServiceError, ServerUnaryCall, ServerWritableStream, ServerReadableStream, ServerDuplexStream, ClientUnaryCall, ClientWritableStream, ClientReadableStream, ClientDuplexStream.

The .proto files themselves are not re-exported from index.ts; raw schema access is via the package.json "./protos/*" export subpath (§1.1).

17. Service Consumer Pattern#

This section shows the complete, four-step pattern for establishing a gRPC client connection using @oshun/proto. Every step is deliberate: using PROTO_PATHS avoids hard-coded file paths, await loadProto is required because schema parsing is async, reading the service constructor from the package object (not from SERVICE_NAMES) ensures the wire-correct name is used, and passing DEFAULT_CHANNEL_OPTIONS gives the connection the correct keepalive and message-size settings.

A domain service that calls a gRPC service does the following (the pattern is exercised by proto.spec.ts's loadProto assertions):

import {
  loadProto,
  PROTO_PATHS,
  createCredentials,
  DEFAULT_CHANNEL_OPTIONS,
} from '@oshun/proto';

// 1. Load the schema (async — loadProto returns a Promise).
const pkg = await loadProto(PROTO_PATHS.isis);

// 2. Read the service constructor from the package object, at the
//    .proto-declared fully-qualified path (package + service name).
const IsisJobService = (pkg as any).oshun.isis.IsisJobService;

// 3. Construct a client with centralized credentials + channel options.
const client = new IsisJobService(
  'isis-service:50051',
  createCredentials(process.env.NODE_ENV === 'production'),
  DEFAULT_CHANNEL_OPTIONS
);

// 4. Call an RPC. Field names follow keepCase:true — snake_case as declared.
client.getQueueStats({ queue_name: 'default' }, (err, response) => {
  if (err) throw err;
  console.log(response.pending_jobs);
});

Key points implied by the source:

• loadProto is async — callers must await it (or .then).
• The service is read from the package object at its .proto-declared path. For procedural and reflection this is the .proto service name (ProceduralGenService, ServerReflectionService), not the SERVICE_NAMES value (§13).
• Because DEFAULT_LOADER_OPTIONS sets keepCase: true, request/response field names at runtime are snake_case exactly as declared in the .proto. (Code generated by buf generate via ts-proto uses snakeToCamel=true and is therefore camelCased — the runtime-loader path and the codegen path differ on this point.)
• createCredentials(false) for local/insecure, createCredentials(true, ...) for TLS (§5.3).

18. Integration Points#

@oshun/proto sits at the bottom of the dependency graph: it imports no other Oshun library, and every domain that uses gRPC depends on it. The table below maps each schema area to its owning or primary consuming domain, so an engineer can find the right .proto file for a given domain without grepping the full tree.

@oshun/proto is a leaf dependency — it imports no other Oshun library, and any domain that speaks gRPC depends on it for the loader, registries, and channel helpers. Observed schema-to-domain ownership:

REST-over-HTTP contracts for external-facing APIs are owned separately (the @oshun/openapi domain). @oshun/proto owns only the gRPC schema mechanics and the runtime loading helpers.