@pulsefield/protocol 0.0.2 → 0.0.3

package/PROTOCOL_GUIDELINES.md

@@ -0,0 +1,123 @@
+# Protocol Guidelines
+
+## Intent
+
+This package defines the shared protobuf contract for Pulsefield clients and model services. The goal is to keep the protocol easy to evolve while avoiding accidental wire-format breakage.
+
+## Change Policy
+
+During early `0.x` development, breaking changes are allowed when all known consumers are updated in the same release.
+
+Once the protocol is used by independently updated clients, prefer additive changes:
+
+- Add new fields with fresh numbers.
+- Add new enum values with fresh numbers.
+- Add new `Envelope.payload` variants with fresh numbers.
+
+Avoid reusing field numbers from published schemas. If a field was removed after publication, reserve its old number and name when practical.
+
+Moving a message to another `.proto` file can preserve its fully qualified protobuf type name and binary wire compatibility, but it changes generated module/file boundaries in languages such as Python. Treat those moves as generated API breaks during `0.x`, document the import migration, and update known consumers in the same release.
+
+## Source Of Truth
+
+- `.proto` files under `proto/` are the source of truth.
+- Keep transport, graph/core vocabulary, inference, and opaque mapper token events in separate source files when the concepts can evolve independently.
+- Breaking-change checks use package-level compatibility so source files can be reorganized without treating stable fully qualified type moves as wire breaks.
+- Generated code under `gen/` is committed for Swift/Python consumers.
+- WebSocket payloads should use binary protobuf `Envelope`.
+
+## Responsibility Boundary
+
+This package should contain stable, cross-process protocol contracts:
+
+- Node graph identity, roles, and capability announcements for host, player client, model service, hardware, and debug-tool processes.
+- Inference endpoint messages and lifecycle states.
+- Machine-readable enums and error codes shared by Swift, Python, and npm consumers.
+- Opaque token-stream events tagged with the token-contract version needed by Swift/model-side decoders.
+- Generated artifacts that prove those contracts are stable.
+
+Keep implementation details in their owning repositories:
+
+- Model training, Torch runtime, checkpoint loading, mel/control features, grammar decoding, and timing fitting algorithms stay in `Pulsefield-model`.
+- Token decoding, decoded Mania4K/domain state, SwiftUI view state, AVFoundation clocks, input routing, rendering, judgement, scoring, and local-library/recognition integrations stay in `Pulsefield`.
+- Full `.osu` import/export behavior stays outside this protocol.
+
+## Inference Lifecycle
+
+The v1 endpoint lifecycle is:
+
+```text
+ready -> audio_preparing -> audio_ready -> streaming -> stopped
+                                      \-> failed
+```
+
+Use `StatusEvent` when a service sends lifecycle transitions over the protocol. The current model endpoint logs `ws_status`; new protobuf consumers should prefer `StatusEvent`.
+
+## Token Contract
+
+The protobuf layer treats mapper tokens as opaque ids plus `token_contract_version`. Token decoding tables, lane actions, quantization rules, and reducer/domain state belong in the Swift and model repositories that share the token-stream transport definitions.
+
+## Comments
+
+Comments should explain protocol meaning, not restate the field name.
+
+Add comments when:
+
+- A message represents a wire-level event or request.
+- A field has units, clock source, ordering semantics, or lifecycle assumptions.
+- A field is optional and absence has a distinct meaning.
+- An enum value is non-obvious.
+- A value is experimental or temporary.
+- A field exists for compatibility with a specific consumer.
+
+Prefer comments like:
+
+```proto
+// Sent by the client to request beatmap inference for an audio source.
+message AudioRequest {
+  // Local or sandbox-relative path understood by the receiving model service.
+  string audio_path = 1;
+
+  // Duration of the selected audio in milliseconds, when known by the client.
+  optional uint32 audio_length_ms = 2;
+}
+```
+
+Avoid comments like:
+
+```proto
+// The audio path.
+string audio_path = 1;
+```
+
+## Naming And Units
+
+- Use `snake_case` field names.
+- Include units in names when they clarify meaning, such as `_ms`, `_unix_ms`, `_count`, or `_id`.
+- Use `*_UNSPECIFIED = 0` for enum defaults.
+- Prefer enums for machine-readable state.
+- Use strings for human-facing or debug messages.
+
+## Validation
+
+The schema defines shape. Runtime code still validates behavior:
+
+- Payload is present.
+- `session_id` is known.
+- `sequence` ordering is acceptable.
+- Time values are in expected ranges.
+- State transitions make sense.
+
+## Workflow
+
+Use local npm scripts:
+
+```sh
+npm run generate
+npm run proto:format
+npm run proto:lint
+npm run generated:check
+npm run check
+```
+
+Generated Swift/Python files must be updated in the same change as proto edits. `npm run generated:check` compares committed outputs with fresh Buf generation and checks that Python stubs and Swift generated code expose the same proto surface.

package/Package.swift

@@ -0,0 +1,34 @@
+// swift-tools-version: 6.0
+
+import PackageDescription
+
+let package = Package(
+    name: "PulsefieldProtocol",
+    products: [
+        .library(
+            name: "PulsefieldProtocol",
+            targets: ["PulsefieldProtocol"]
+        )
+    ],
+    dependencies: [
+        .package(
+            url: "https://github.com/apple/swift-protobuf.git",
+            from: "1.38.0"
+        )
+    ],
+    targets: [
+        .target(
+            name: "PulsefieldProtocol",
+            dependencies: [
+                .product(name: "SwiftProtobuf", package: "swift-protobuf")
+            ],
+            path: "gen/swift",
+            sources: [
+                "pulsefield/protocol/v1/core.pb.swift",
+                "pulsefield/protocol/v1/envelope.pb.swift",
+                "pulsefield/protocol/v1/inference.pb.swift",
+                "pulsefield/protocol/v1/mapper.pb.swift",
+            ]
+        )
+    ]
+)

package/README.md

@@ -8,12 +8,95 @@ Shared protocol package for projects under [github.com/Pulsefield](https://githu
 proto/              Protocol Buffers source of truth.
 gen/swift/          Generated SwiftProtobuf code, committed and shipped.
 gen/python/         Generated Python protobuf code and type stubs, committed and shipped.
-fixtures/json/      Protobuf JSON mapping fixtures for debug and tests.
+docs/               Protocol notes shipped with the npm package.
+tools/              Local generation and drift-check scripts.
+Package.swift       SwiftPM manifest for Swift/Xcode consumers.
+pyproject.toml      Python package metadata for wheel/sdist consumers.
 buf.yaml            Proto lint and breaking-change configuration.
 buf.gen.yaml        Swift and Python generation configuration.
 ```
 
-The Swift app and Python model consume generated code from `gen/`. The `.proto` files remain the protocol source of truth. WebSocket payloads should be binary protobuf `Envelope` messages. JSON is reserved for debug, logs, and fixtures.
+The Swift app and Python model consume generated code from `gen/`. The `.proto` files remain the protocol source of truth. WebSocket payloads should be binary protobuf `Envelope` messages. JSON is reserved for debug and logs.
+
+See [Protocol Guidelines](./PROTOCOL_GUIDELINES.md) for schema evolution, naming, and comment conventions. See [Session Scope](./docs/session-scope.md) for `Envelope.session_id` requirements by payload.
+
+The v1 protobuf source is split by responsibility:
+
+```text
+proto/pulsefield/protocol/v1/core.proto
+  Node identity, roles, and advertised capabilities.
+
+proto/pulsefield/protocol/v1/envelope.proto
+  Transport envelope, routing metadata, correlation ids, and payload union.
+
+proto/pulsefield/protocol/v1/inference.proto
+  Inference requests, lifecycle status, errors, and end-of-stream events.
+
+proto/pulsefield/protocol/v1/mapper.proto
+  Opaque mapper token events.
+```
+
+## Current Scope
+
+This package owns the stable cross-language contract between Pulsefield clients, the Python model endpoint, and npm consumers:
+
+- Node graph identity for host, player client, model service, hardware, and debug-tool processes.
+- Inference WebSocket envelopes: ready, audio, reference time, stop, status, error, hitobject token, and end-of-stream.
+- Opaque mapper token stream events tagged with a token-contract version.
+
+This package does not own token decoding, decoded Mania4K/domain state, model inference internals, Torch checkpoints, timing fitting algorithms, SwiftUI state, rendering, judgement, input routing, audio clock implementations, or full `.osu` parsing/export.
+
+## Distribution Surfaces
+
+This repository publishes the same protocol contract through multiple language-native surfaces. Downstream Swift and Python projects do not need their own `package.json`.
+
+### npm
+
+The npm package remains useful for Node tooling, registry-backed tarballs, and consumers that want direct access to `proto/` and `gen/`:
+
+```sh
+npm install @pulsefield/protocol
+```
+
+### SwiftPM
+
+Swift/Xcode consumers should depend on this Git repository directly:
+
+```swift
+.package(
+    url: "https://github.com/Pulsefield/protocol.git",
+    from: "0.0.3"
+)
+```
+
+Then add the product to a target:
+
+```swift
+.product(name: "PulsefieldProtocol", package: "protocol")
+```
+
+SwiftPM publication is Git-tag based. Create and push a semver tag such as `0.0.3`; no central Swift registry is required for this bootstrap path.
+
+### Python
+
+Python consumers should eventually use the PyPI package:
+
+```sh
+pip install pulsefield-protocol==0.0.3
+```
+
+The local bootstrap build is:
+
+```sh
+python3 -m pip install build
+python3 -m build --sdist --wheel --outdir dist/
+python3 -m pip install dist/*.whl
+python3 -c "from pulsefield.protocol.v1 import envelope_pb2; envelope_pb2.Envelope()"
+```
+
+Generated Python classes live in the module for their source `.proto` file. For example, import `Envelope` from `envelope_pb2`, inference messages from `inference_pb2`, mapper token messages from `mapper_pb2`, and node graph messages from `core_pb2`.
+
+The `Publish Python package` GitHub workflow is manual and expects PyPI trusted publishing to be configured for the repository/environment before it is run.
 
 ## Development Tools
 
@@ -23,18 +106,23 @@ The Swift app and Python model consume generated code from `gen/`. The `.proto`
 - Proto lint/generation: `@bufbuild/buf`.
 - Swift generation: Buf remote plugin `buf.build/apple/swift`.
 - Python generation: Buf remote plugins `buf.build/protocolbuffers/python` and `buf.build/protocolbuffers/pyi`.
-- TypeScript checks: `typescript`.
-- Tests: `vitest`.
 - Formatting: `prettier`.
 
 ## Commands
 
 ```sh
+npm run generate
 npm run proto:lint
 npm run proto:generate
+npm run generated:check
 npm run check
+npm run python:check
+npm run swift:build
+npm run bootstrap:check
 ```
 
+`npm run generated:check` regenerates Swift and Python outputs in a temporary directory and compares them byte-for-byte with `gen/`. It also verifies that the generated Python stubs and Swift file expose the same message, enum, and field surface declared by the proto.
+
 ## License
 
 Licensed under the Apache License, Version 2.0. See [LICENSE](./LICENSE).

package/buf.yaml

@@ -6,4 +6,4 @@ lint:
     - STANDARD
 breaking:
   use:
-    - FILE
+    - PACKAGE

package/docs/session-scope.md

@@ -0,0 +1,27 @@
+# Session Scope
+
+`Envelope.session_id` defines the session scope for the envelope payload. Payload
+messages do not duplicate `session_id`; receivers validate the payload against the
+session id carried by the envelope.
+
+## Rules
+
+| Payload                | `Envelope.session_id`                                                                     |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| `NodeHello`            | MUST be empty                                                                             |
+| `ReadyRequest`         | SHOULD be empty                                                                           |
+| `AudioRequest`         | MUST be non-empty                                                                         |
+| `ReferenceTimeRequest` | MUST be non-empty                                                                         |
+| `HitObjectTokenEvent`  | MUST be non-empty                                                                         |
+| `StopSessionRequest`   | MUST be non-empty                                                                         |
+| `StatusEvent`          | MAY be empty for endpoint/node-scoped status; MUST be non-empty for session-scoped status |
+
+`StopSessionRequest` intentionally has no `session_id` field. It targets the
+active session identified by `Envelope.session_id`; therefore an envelope with
+`payload.stop_session` and an empty `Envelope.session_id` is invalid.
+
+`StatusEvent` is the only payload in this list that can validly cross the
+session boundary. Endpoint-level statuses such as cold startup or readiness can
+use an empty `Envelope.session_id`. Statuses describing an active session, a
+missing session, or a session transition use the relevant non-empty
+`Envelope.session_id`.

package/gen/python/pulsefield/protocol/py.typed

@@ -0,0 +1 @@
+

package/gen/python/pulsefield/protocol/v1/core_pb2.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: pulsefield/protocol/v1/core.proto
+# Protobuf Python Version: 5.26.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n!pulsefield/protocol/v1/core.proto\x12\x16pulsefield.protocol.v1\"\xcd\x01\n\x0eNodeCapability\x12>\n\x04kind\x18\x01 \x01(\x0e\x32*.pulsefield.protocol.v1.NodeCapabilityKindR\x04kind\x12\x12\n\x04name\x18\x02 \x01(\tR\x04name\x12\x18\n\x07version\x18\x03 \x01(\tR\x07version\x12M\n\tdirection\x18\x04 \x01(\x0e\x32/.pulsefield.protocol.v1.NodeCapabilityDirectionR\tdirection\"\xe8\x01\n\tNodeHello\x12\x17\n\x07node_id\x18\x01 \x01(\tR\x06nodeId\x12\x34\n\x04role\x18\x02 \x01(\x0e\x32 .pulsefield.protocol.v1.NodeRoleR\x04role\x12J\n\x0c\x63\x61pabilities\x18\x03 \x03(\x0b\x32&.pulsefield.protocol.v1.NodeCapabilityR\x0c\x63\x61pabilities\x12)\n\x10protocol_version\x18\x04 \x01(\tR\x0fprotocolVersion\x12\x15\n\x06\x61pp_id\x18\x05 \x01(\tR\x05\x61ppId*\xa5\x01\n\x08NodeRole\x12\x19\n\x15NODE_ROLE_UNSPECIFIED\x10\x00\x12\x12\n\x0eNODE_ROLE_HOST\x10\x01\x12\x1b\n\x17NODE_ROLE_PLAYER_CLIENT\x10\x02\x12\x1b\n\x17NODE_ROLE_MODEL_SERVICE\x10\x03\x12\x16\n\x12NODE_ROLE_HARDWARE\x10\x04\x12\x18\n\x14NODE_ROLE_DEBUG_TOOL\x10\x05*\x8d\x02\n\x12NodeCapabilityKind\x12$\n NODE_CAPABILITY_KIND_UNSPECIFIED\x10\x00\x12$\n NODE_CAPABILITY_KIND_RECOGNITION\x10\x01\x12\x1f\n\x1bNODE_CAPABILITY_KIND_TIMING\x10\x02\x12\x1f\n\x1bNODE_CAPABILITY_KIND_MAPPER\x10\x03\x12&\n\"NODE_CAPABILITY_KIND_PLAYER_STREAM\x10\x04\x12!\n\x1dNODE_CAPABILITY_KIND_HARDWARE\x10\x05\x12\x1e\n\x1aNODE_CAPABILITY_KIND_DEBUG\x10\x06*\xc1\x01\n\x17NodeCapabilityDirection\x12)\n%NODE_CAPABILITY_DIRECTION_UNSPECIFIED\x10\x00\x12&\n\"NODE_CAPABILITY_DIRECTION_PRODUCER\x10\x01\x12&\n\"NODE_CAPABILITY_DIRECTION_CONSUMER\x10\x02\x12+\n\'NODE_CAPABILITY_DIRECTION_BIDIRECTIONAL\x10\x03\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'pulsefield.protocol.v1.core_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_NODEROLE']._serialized_start=505
+  _globals['_NODEROLE']._serialized_end=670
+  _globals['_NODECAPABILITYKIND']._serialized_start=673
+  _globals['_NODECAPABILITYKIND']._serialized_end=942
+  _globals['_NODECAPABILITYDIRECTION']._serialized_start=945
+  _globals['_NODECAPABILITYDIRECTION']._serialized_end=1138
+  _globals['_NODECAPABILITY']._serialized_start=62
+  _globals['_NODECAPABILITY']._serialized_end=267
+  _globals['_NODEHELLO']._serialized_start=270
+  _globals['_NODEHELLO']._serialized_end=502
+# @@protoc_insertion_point(module_scope)

package/gen/python/pulsefield/protocol/v1/core_pb2.pyi

@@ -0,0 +1,76 @@
+from google.protobuf.internal import containers as _containers
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Iterable as _Iterable, Mapping as _Mapping, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class NodeRole(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    NODE_ROLE_UNSPECIFIED: _ClassVar[NodeRole]
+    NODE_ROLE_HOST: _ClassVar[NodeRole]
+    NODE_ROLE_PLAYER_CLIENT: _ClassVar[NodeRole]
+    NODE_ROLE_MODEL_SERVICE: _ClassVar[NodeRole]
+    NODE_ROLE_HARDWARE: _ClassVar[NodeRole]
+    NODE_ROLE_DEBUG_TOOL: _ClassVar[NodeRole]
+
+class NodeCapabilityKind(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    NODE_CAPABILITY_KIND_UNSPECIFIED: _ClassVar[NodeCapabilityKind]
+    NODE_CAPABILITY_KIND_RECOGNITION: _ClassVar[NodeCapabilityKind]
+    NODE_CAPABILITY_KIND_TIMING: _ClassVar[NodeCapabilityKind]
+    NODE_CAPABILITY_KIND_MAPPER: _ClassVar[NodeCapabilityKind]
+    NODE_CAPABILITY_KIND_PLAYER_STREAM: _ClassVar[NodeCapabilityKind]
+    NODE_CAPABILITY_KIND_HARDWARE: _ClassVar[NodeCapabilityKind]
+    NODE_CAPABILITY_KIND_DEBUG: _ClassVar[NodeCapabilityKind]
+
+class NodeCapabilityDirection(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    NODE_CAPABILITY_DIRECTION_UNSPECIFIED: _ClassVar[NodeCapabilityDirection]
+    NODE_CAPABILITY_DIRECTION_PRODUCER: _ClassVar[NodeCapabilityDirection]
+    NODE_CAPABILITY_DIRECTION_CONSUMER: _ClassVar[NodeCapabilityDirection]
+    NODE_CAPABILITY_DIRECTION_BIDIRECTIONAL: _ClassVar[NodeCapabilityDirection]
+NODE_ROLE_UNSPECIFIED: NodeRole
+NODE_ROLE_HOST: NodeRole
+NODE_ROLE_PLAYER_CLIENT: NodeRole
+NODE_ROLE_MODEL_SERVICE: NodeRole
+NODE_ROLE_HARDWARE: NodeRole
+NODE_ROLE_DEBUG_TOOL: NodeRole
+NODE_CAPABILITY_KIND_UNSPECIFIED: NodeCapabilityKind
+NODE_CAPABILITY_KIND_RECOGNITION: NodeCapabilityKind
+NODE_CAPABILITY_KIND_TIMING: NodeCapabilityKind
+NODE_CAPABILITY_KIND_MAPPER: NodeCapabilityKind
+NODE_CAPABILITY_KIND_PLAYER_STREAM: NodeCapabilityKind
+NODE_CAPABILITY_KIND_HARDWARE: NodeCapabilityKind
+NODE_CAPABILITY_KIND_DEBUG: NodeCapabilityKind
+NODE_CAPABILITY_DIRECTION_UNSPECIFIED: NodeCapabilityDirection
+NODE_CAPABILITY_DIRECTION_PRODUCER: NodeCapabilityDirection
+NODE_CAPABILITY_DIRECTION_CONSUMER: NodeCapabilityDirection
+NODE_CAPABILITY_DIRECTION_BIDIRECTIONAL: NodeCapabilityDirection
+
+class NodeCapability(_message.Message):
+    __slots__ = ("kind", "name", "version", "direction")
+    KIND_FIELD_NUMBER: _ClassVar[int]
+    NAME_FIELD_NUMBER: _ClassVar[int]
+    VERSION_FIELD_NUMBER: _ClassVar[int]
+    DIRECTION_FIELD_NUMBER: _ClassVar[int]
+    kind: NodeCapabilityKind
+    name: str
+    version: str
+    direction: NodeCapabilityDirection
+    def __init__(self, kind: _Optional[_Union[NodeCapabilityKind, str]] = ..., name: _Optional[str] = ..., version: _Optional[str] = ..., direction: _Optional[_Union[NodeCapabilityDirection, str]] = ...) -> None: ...
+
+class NodeHello(_message.Message):
+    __slots__ = ("node_id", "role", "capabilities", "protocol_version", "app_id")
+    NODE_ID_FIELD_NUMBER: _ClassVar[int]
+    ROLE_FIELD_NUMBER: _ClassVar[int]
+    CAPABILITIES_FIELD_NUMBER: _ClassVar[int]
+    PROTOCOL_VERSION_FIELD_NUMBER: _ClassVar[int]
+    APP_ID_FIELD_NUMBER: _ClassVar[int]
+    node_id: str
+    role: NodeRole
+    capabilities: _containers.RepeatedCompositeFieldContainer[NodeCapability]
+    protocol_version: str
+    app_id: str
+    def __init__(self, node_id: _Optional[str] = ..., role: _Optional[_Union[NodeRole, str]] = ..., capabilities: _Optional[_Iterable[_Union[NodeCapability, _Mapping]]] = ..., protocol_version: _Optional[str] = ..., app_id: _Optional[str] = ...) -> None: ...

package/gen/python/pulsefield/protocol/v1/envelope_pb2.py

@@ -12,35 +12,18 @@ from google.protobuf.internal import builder as _builder
 _sym_db = _symbol_database.Default()
 
 
+from pulsefield.protocol.v1 import core_pb2 as pulsefield_dot_protocol_dot_v1_dot_core__pb2
+from pulsefield.protocol.v1 import inference_pb2 as pulsefield_dot_protocol_dot_v1_dot_inference__pb2
+from pulsefield.protocol.v1 import mapper_pb2 as pulsefield_dot_protocol_dot_v1_dot_mapper__pb2
 
 
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n%pulsefield/protocol/v1/envelope.proto\x12\x16pulsefield.protocol.v1\"\xef\x04\n\x08\x45nvelope\x12\x1d\n\nsession_id\x18\x01 \x01(\tR\tsessionId\x12\x1a\n\x08sequence\x18\x02 \x01(\x04R\x08sequence\x12%\n\x0fsent_at_unix_ms\x18\x03 \x01(\x03R\x0csentAtUnixMs\x12<\n\x05ready\x18\n \x01(\x0b\x32$.pulsefield.protocol.v1.ReadyRequestH\x00R\x05ready\x12<\n\x05\x61udio\x18\x0b \x01(\x0b\x32$.pulsefield.protocol.v1.AudioRequestH\x00R\x05\x61udio\x12U\n\x0ereference_time\x18\x0c \x01(\x0b\x32,.pulsefield.protocol.v1.ReferenceTimeRequestH\x00R\rreferenceTime\x12O\n\x0cstop_session\x18\r \x01(\x0b\x32*.pulsefield.protocol.v1.StopSessionRequestH\x00R\x0bstopSession\x12W\n\x10hit_object_token\x18\x14 \x01(\x0b\x32+.pulsefield.protocol.v1.HitObjectTokenEventH\x00R\x0ehitObjectToken\x12:\n\x05\x65rror\x18\x15 \x01(\x0b\x32\".pulsefield.protocol.v1.ErrorEventH\x00R\x05\x65rror\x12=\n\x06status\x18\x16 \x01(\x0b\x32#.pulsefield.protocol.v1.StatusEventH\x00R\x06statusB\t\n\x07payload\"\x0e\n\x0cReadyRequest\"\xa8\x02\n\x0c\x41udioRequest\x12\x1d\n\naudio_path\x18\x01 \x01(\tR\taudioPath\x12+\n\x0f\x61udio_length_ms\x18\x02 \x01(\rH\x00R\raudioLengthMs\x88\x01\x01\x12\x46\n\x0cmusic_source\x18\x03 \x01(\x0e\x32#.pulsefield.protocol.v1.MusicSourceR\x0bmusicSource\x12#\n\ndifficulty\x18\x04 \x01(\x01H\x01R\ndifficulty\x88\x01\x01\x12<\n\x05route\x18\x05 \x01(\x0e\x32&.pulsefield.protocol.v1.InferenceRouteR\x05routeB\x12\n\x10_audio_length_msB\r\n\x0b_difficulty\"\xad\x01\n\x14ReferenceTimeRequest\x12\x1e\n\x0bref_time_ms\x18\x01 \x01(\rR\trefTimeMs\x12\x34\n\x17local_host_time_send_ms\x18\x02 \x01(\x01R\x13localHostTimeSendMs\x12+\n\x0f\x61udio_length_ms\x18\x03 \x01(\rH\x00R\raudioLengthMs\x88\x01\x01\x42\x12\n\x10_audio_length_ms\",\n\x12StopSessionRequest\x12\x16\n\x06reason\x18\x01 \x01(\tR\x06reason\"W\n\x13HitObjectTokenEvent\x12\x19\n\x08token_id\x18\x01 \x01(\rR\x07tokenId\x12%\n\x0fms_in_ref_audio\x18\x02 \x01(\rR\x0cmsInRefAudio\":\n\nErrorEvent\x12\x12\n\x04\x63ode\x18\x01 \x01(\tR\x04\x63ode\x12\x18\n\x07message\x18\x02 \x01(\tR\x07message\"\xb4\x01\n\x0bStatusEvent\x12>\n\x06status\x18\x01 \x01(\x0e\x32&.pulsefield.protocol.v1.EndpointStatusR\x06status\x12\x18\n\x07message\x18\x02 \x01(\tR\x07message\x12\x1e\n\x0bref_time_ms\x18\x03 \x01(\rR\trefTimeMs\x12+\n\x12local_host_time_ms\x18\x04 \x01(\x01R\x0flocalHostTimeMs*g\n\x0bMusicSource\x12\x1c\n\x18MUSIC_SOURCE_UNSPECIFIED\x10\x00\x12\x1b\n\x17MUSIC_SOURCE_BACKGROUND\x10\x01\x12\x1d\n\x19MUSIC_SOURCE_SYSTEM_AUDIO\x10\x02*n\n\x0eInferenceRoute\x12\x1f\n\x1bINFERENCE_ROUTE_UNSPECIFIED\x10\x00\x12\x1a\n\x16INFERENCE_ROUTE_MAPPER\x10\x01\x12\x1f\n\x1bINFERENCE_ROUTE_TIMING_MOCK\x10\x02*\xce\x01\n\x0e\x45ndpointStatus\x12\x1f\n\x1b\x45NDPOINT_STATUS_UNSPECIFIED\x10\x00\x12\x19\n\x15\x45NDPOINT_STATUS_READY\x10\x01\x12#\n\x1f\x45NDPOINT_STATUS_AUDIO_PREPARING\x10\x02\x12\x1f\n\x1b\x45NDPOINT_STATUS_AUDIO_READY\x10\x03\x12\x1d\n\x19\x45NDPOINT_STATUS_STREAMING\x10\x04\x12\x1b\n\x17\x45NDPOINT_STATUS_STOPPED\x10\x05\x62\x06proto3')
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n%pulsefield/protocol/v1/envelope.proto\x12\x16pulsefield.protocol.v1\x1a!pulsefield/protocol/v1/core.proto\x1a&pulsefield/protocol/v1/inference.proto\x1a#pulsefield/protocol/v1/mapper.proto\"\xf7\x07\n\x08\x45nvelope\x12\x1d\n\nsession_id\x18\x01 \x01(\tR\tsessionId\x12\x1a\n\x08sequence\x18\x02 \x01(\x04R\x08sequence\x12%\n\x0fsent_at_unix_ms\x18\x03 \x01(\x03R\x0csentAtUnixMs\x12$\n\x0esource_node_id\x18\x04 \x01(\tR\x0csourceNodeId\x12$\n\x0etarget_node_id\x18\x05 \x01(\tR\x0ctargetNodeId\x12\x1d\n\nmessage_id\x18\x06 \x01(\tR\tmessageId\x12%\n\x0e\x63orrelation_id\x18\x07 \x01(\tR\rcorrelationId\x12\x42\n\nnode_hello\x18\x08 \x01(\x0b\x32!.pulsefield.protocol.v1.NodeHelloH\x00R\tnodeHello\x12<\n\x05ready\x18\n \x01(\x0b\x32$.pulsefield.protocol.v1.ReadyRequestH\x00R\x05ready\x12<\n\x05\x61udio\x18\x0b \x01(\x0b\x32$.pulsefield.protocol.v1.AudioRequestH\x00R\x05\x61udio\x12U\n\x0ereference_time\x18\x0c \x01(\x0b\x32,.pulsefield.protocol.v1.ReferenceTimeRequestH\x00R\rreferenceTime\x12O\n\x0cstop_session\x18\r \x01(\x0b\x32*.pulsefield.protocol.v1.StopSessionRequestH\x00R\x0bstopSession\x12`\n\x13mapper_stream_begin\x18\x13 \x01(\x0b\x32..pulsefield.protocol.v1.MapperStreamBeginEventH\x00R\x11mapperStreamBegin\x12W\n\x10hit_object_token\x18\x14 \x01(\x0b\x32+.pulsefield.protocol.v1.HitObjectTokenEventH\x00R\x0ehitObjectToken\x12:\n\x05\x65rror\x18\x15 \x01(\x0b\x32\".pulsefield.protocol.v1.ErrorEventH\x00R\x05\x65rror\x12=\n\x06status\x18\x16 \x01(\x0b\x32#.pulsefield.protocol.v1.StatusEventH\x00R\x06status\x12N\n\rend_of_stream\x18\x17 \x01(\x0b\x32(.pulsefield.protocol.v1.EndOfStreamEventH\x00R\x0b\x65ndOfStreamB\t\n\x07payloadb\x06proto3')
 
 _globals = globals()
 _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
 _builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'pulsefield.protocol.v1.envelope_pb2', _globals)
 if not _descriptor._USE_C_DESCRIPTORS:
   DESCRIPTOR._loaded_options = None
-  _globals['_MUSICSOURCE']._serialized_start=1560
-  _globals['_MUSICSOURCE']._serialized_end=1663
-  _globals['_INFERENCEROUTE']._serialized_start=1665
-  _globals['_INFERENCEROUTE']._serialized_end=1775
-  _globals['_ENDPOINTSTATUS']._serialized_start=1778
-  _globals['_ENDPOINTSTATUS']._serialized_end=1984
-  _globals['_ENVELOPE']._serialized_start=66
-  _globals['_ENVELOPE']._serialized_end=689
-  _globals['_READYREQUEST']._serialized_start=691
-  _globals['_READYREQUEST']._serialized_end=705
-  _globals['_AUDIOREQUEST']._serialized_start=708
-  _globals['_AUDIOREQUEST']._serialized_end=1004
-  _globals['_REFERENCETIMEREQUEST']._serialized_start=1007
-  _globals['_REFERENCETIMEREQUEST']._serialized_end=1180
-  _globals['_STOPSESSIONREQUEST']._serialized_start=1182
-  _globals['_STOPSESSIONREQUEST']._serialized_end=1226
-  _globals['_HITOBJECTTOKENEVENT']._serialized_start=1228
-  _globals['_HITOBJECTTOKENEVENT']._serialized_end=1315
-  _globals['_ERROREVENT']._serialized_start=1317
-  _globals['_ERROREVENT']._serialized_end=1375
-  _globals['_STATUSEVENT']._serialized_start=1378
-  _globals['_STATUSEVENT']._serialized_end=1558
+  _globals['_ENVELOPE']._serialized_start=178
+  _globals['_ENVELOPE']._serialized_end=1193
 # @@protoc_insertion_point(module_scope)

package/gen/python/pulsefield/protocol/v1/envelope_pb2.pyi

@@ -1,125 +1,46 @@
-from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from pulsefield.protocol.v1 import core_pb2 as _core_pb2
+from pulsefield.protocol.v1 import inference_pb2 as _inference_pb2
+from pulsefield.protocol.v1 import mapper_pb2 as _mapper_pb2
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import message as _message
 from typing import ClassVar as _ClassVar, Mapping as _Mapping, Optional as _Optional, Union as _Union
 
 DESCRIPTOR: _descriptor.FileDescriptor
 
-class MusicSource(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
-    __slots__ = ()
-    MUSIC_SOURCE_UNSPECIFIED: _ClassVar[MusicSource]
-    MUSIC_SOURCE_BACKGROUND: _ClassVar[MusicSource]
-    MUSIC_SOURCE_SYSTEM_AUDIO: _ClassVar[MusicSource]
-
-class InferenceRoute(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
-    __slots__ = ()
-    INFERENCE_ROUTE_UNSPECIFIED: _ClassVar[InferenceRoute]
-    INFERENCE_ROUTE_MAPPER: _ClassVar[InferenceRoute]
-    INFERENCE_ROUTE_TIMING_MOCK: _ClassVar[InferenceRoute]
-
-class EndpointStatus(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
-    __slots__ = ()
-    ENDPOINT_STATUS_UNSPECIFIED: _ClassVar[EndpointStatus]
-    ENDPOINT_STATUS_READY: _ClassVar[EndpointStatus]
-    ENDPOINT_STATUS_AUDIO_PREPARING: _ClassVar[EndpointStatus]
-    ENDPOINT_STATUS_AUDIO_READY: _ClassVar[EndpointStatus]
-    ENDPOINT_STATUS_STREAMING: _ClassVar[EndpointStatus]
-    ENDPOINT_STATUS_STOPPED: _ClassVar[EndpointStatus]
-MUSIC_SOURCE_UNSPECIFIED: MusicSource
-MUSIC_SOURCE_BACKGROUND: MusicSource
-MUSIC_SOURCE_SYSTEM_AUDIO: MusicSource
-INFERENCE_ROUTE_UNSPECIFIED: InferenceRoute
-INFERENCE_ROUTE_MAPPER: InferenceRoute
-INFERENCE_ROUTE_TIMING_MOCK: InferenceRoute
-ENDPOINT_STATUS_UNSPECIFIED: EndpointStatus
-ENDPOINT_STATUS_READY: EndpointStatus
-ENDPOINT_STATUS_AUDIO_PREPARING: EndpointStatus
-ENDPOINT_STATUS_AUDIO_READY: EndpointStatus
-ENDPOINT_STATUS_STREAMING: EndpointStatus
-ENDPOINT_STATUS_STOPPED: EndpointStatus
-
 class Envelope(_message.Message):
-    __slots__ = ("session_id", "sequence", "sent_at_unix_ms", "ready", "audio", "reference_time", "stop_session", "hit_object_token", "error", "status")
+    __slots__ = ("session_id", "sequence", "sent_at_unix_ms", "source_node_id", "target_node_id", "message_id", "correlation_id", "node_hello", "ready", "audio", "reference_time", "stop_session", "mapper_stream_begin", "hit_object_token", "error", "status", "end_of_stream")
     SESSION_ID_FIELD_NUMBER: _ClassVar[int]
     SEQUENCE_FIELD_NUMBER: _ClassVar[int]
     SENT_AT_UNIX_MS_FIELD_NUMBER: _ClassVar[int]
+    SOURCE_NODE_ID_FIELD_NUMBER: _ClassVar[int]
+    TARGET_NODE_ID_FIELD_NUMBER: _ClassVar[int]
+    MESSAGE_ID_FIELD_NUMBER: _ClassVar[int]
+    CORRELATION_ID_FIELD_NUMBER: _ClassVar[int]
+    NODE_HELLO_FIELD_NUMBER: _ClassVar[int]
     READY_FIELD_NUMBER: _ClassVar[int]
     AUDIO_FIELD_NUMBER: _ClassVar[int]
     REFERENCE_TIME_FIELD_NUMBER: _ClassVar[int]
     STOP_SESSION_FIELD_NUMBER: _ClassVar[int]
+    MAPPER_STREAM_BEGIN_FIELD_NUMBER: _ClassVar[int]
     HIT_OBJECT_TOKEN_FIELD_NUMBER: _ClassVar[int]
     ERROR_FIELD_NUMBER: _ClassVar[int]
     STATUS_FIELD_NUMBER: _ClassVar[int]
+    END_OF_STREAM_FIELD_NUMBER: _ClassVar[int]
     session_id: str
     sequence: int
     sent_at_unix_ms: int
-    ready: ReadyRequest
-    audio: AudioRequest
-    reference_time: ReferenceTimeRequest
-    stop_session: StopSessionRequest
-    hit_object_token: HitObjectTokenEvent
-    error: ErrorEvent
-    status: StatusEvent
-    def __init__(self, session_id: _Optional[str] = ..., sequence: _Optional[int] = ..., sent_at_unix_ms: _Optional[int] = ..., ready: _Optional[_Union[ReadyRequest, _Mapping]] = ..., audio: _Optional[_Union[AudioRequest, _Mapping]] = ..., reference_time: _Optional[_Union[ReferenceTimeRequest, _Mapping]] = ..., stop_session: _Optional[_Union[StopSessionRequest, _Mapping]] = ..., hit_object_token: _Optional[_Union[HitObjectTokenEvent, _Mapping]] = ..., error: _Optional[_Union[ErrorEvent, _Mapping]] = ..., status: _Optional[_Union[StatusEvent, _Mapping]] = ...) -> None: ...
-
-class ReadyRequest(_message.Message):
-    __slots__ = ()
-    def __init__(self) -> None: ...
-
-class AudioRequest(_message.Message):
-    __slots__ = ("audio_path", "audio_length_ms", "music_source", "difficulty", "route")
-    AUDIO_PATH_FIELD_NUMBER: _ClassVar[int]
-    AUDIO_LENGTH_MS_FIELD_NUMBER: _ClassVar[int]
-    MUSIC_SOURCE_FIELD_NUMBER: _ClassVar[int]
-    DIFFICULTY_FIELD_NUMBER: _ClassVar[int]
-    ROUTE_FIELD_NUMBER: _ClassVar[int]
-    audio_path: str
-    audio_length_ms: int
-    music_source: MusicSource
-    difficulty: float
-    route: InferenceRoute
-    def __init__(self, audio_path: _Optional[str] = ..., audio_length_ms: _Optional[int] = ..., music_source: _Optional[_Union[MusicSource, str]] = ..., difficulty: _Optional[float] = ..., route: _Optional[_Union[InferenceRoute, str]] = ...) -> None: ...
-
-class ReferenceTimeRequest(_message.Message):
-    __slots__ = ("ref_time_ms", "local_host_time_send_ms", "audio_length_ms")
-    REF_TIME_MS_FIELD_NUMBER: _ClassVar[int]
-    LOCAL_HOST_TIME_SEND_MS_FIELD_NUMBER: _ClassVar[int]
-    AUDIO_LENGTH_MS_FIELD_NUMBER: _ClassVar[int]
-    ref_time_ms: int
-    local_host_time_send_ms: float
-    audio_length_ms: int
-    def __init__(self, ref_time_ms: _Optional[int] = ..., local_host_time_send_ms: _Optional[float] = ..., audio_length_ms: _Optional[int] = ...) -> None: ...
-
-class StopSessionRequest(_message.Message):
-    __slots__ = ("reason",)
-    REASON_FIELD_NUMBER: _ClassVar[int]
-    reason: str
-    def __init__(self, reason: _Optional[str] = ...) -> None: ...
-
-class HitObjectTokenEvent(_message.Message):
-    __slots__ = ("token_id", "ms_in_ref_audio")
-    TOKEN_ID_FIELD_NUMBER: _ClassVar[int]
-    MS_IN_REF_AUDIO_FIELD_NUMBER: _ClassVar[int]
-    token_id: int
-    ms_in_ref_audio: int
-    def __init__(self, token_id: _Optional[int] = ..., ms_in_ref_audio: _Optional[int] = ...) -> None: ...
-
-class ErrorEvent(_message.Message):
-    __slots__ = ("code", "message")
-    CODE_FIELD_NUMBER: _ClassVar[int]
-    MESSAGE_FIELD_NUMBER: _ClassVar[int]
-    code: str
-    message: str
-    def __init__(self, code: _Optional[str] = ..., message: _Optional[str] = ...) -> None: ...
-
-class StatusEvent(_message.Message):
-    __slots__ = ("status", "message", "ref_time_ms", "local_host_time_ms")
-    STATUS_FIELD_NUMBER: _ClassVar[int]
-    MESSAGE_FIELD_NUMBER: _ClassVar[int]
-    REF_TIME_MS_FIELD_NUMBER: _ClassVar[int]
-    LOCAL_HOST_TIME_MS_FIELD_NUMBER: _ClassVar[int]
-    status: EndpointStatus
-    message: str
-    ref_time_ms: int
-    local_host_time_ms: float
-    def __init__(self, status: _Optional[_Union[EndpointStatus, str]] = ..., message: _Optional[str] = ..., ref_time_ms: _Optional[int] = ..., local_host_time_ms: _Optional[float] = ...) -> None: ...
+    source_node_id: str
+    target_node_id: str
+    message_id: str
+    correlation_id: str
+    node_hello: _core_pb2.NodeHello
+    ready: _inference_pb2.ReadyRequest
+    audio: _inference_pb2.AudioRequest
+    reference_time: _inference_pb2.ReferenceTimeRequest
+    stop_session: _inference_pb2.StopSessionRequest
+    mapper_stream_begin: _mapper_pb2.MapperStreamBeginEvent
+    hit_object_token: _mapper_pb2.HitObjectTokenEvent
+    error: _inference_pb2.ErrorEvent
+    status: _inference_pb2.StatusEvent
+    end_of_stream: _inference_pb2.EndOfStreamEvent
+    def __init__(self, session_id: _Optional[str] = ..., sequence: _Optional[int] = ..., sent_at_unix_ms: _Optional[int] = ..., source_node_id: _Optional[str] = ..., target_node_id: _Optional[str] = ..., message_id: _Optional[str] = ..., correlation_id: _Optional[str] = ..., node_hello: _Optional[_Union[_core_pb2.NodeHello, _Mapping]] = ..., ready: _Optional[_Union[_inference_pb2.ReadyRequest, _Mapping]] = ..., audio: _Optional[_Union[_inference_pb2.AudioRequest, _Mapping]] = ..., reference_time: _Optional[_Union[_inference_pb2.ReferenceTimeRequest, _Mapping]] = ..., stop_session: _Optional[_Union[_inference_pb2.StopSessionRequest, _Mapping]] = ..., mapper_stream_begin: _Optional[_Union[_mapper_pb2.MapperStreamBeginEvent, _Mapping]] = ..., hit_object_token: _Optional[_Union[_mapper_pb2.HitObjectTokenEvent, _Mapping]] = ..., error: _Optional[_Union[_inference_pb2.ErrorEvent, _Mapping]] = ..., status: _Optional[_Union[_inference_pb2.StatusEvent, _Mapping]] = ..., end_of_stream: _Optional[_Union[_inference_pb2.EndOfStreamEvent, _Mapping]] = ...) -> None: ...