Merge pull request #40 from FluffyAIcode/AgentMemory/v030-pr-a1-runtime-proto-8e7f

PR-A1 (ADR 0008 Phase A): runtime.proto + buf lint CI gate

Author: FluffyAIcode

.github/workflows/ci.yaml

@@ -175,3 +175,38 @@ jobs:
           docker run --rm \
             kakeya:ci-${{ github.sha }} \
             --help
+
+  proto-lint:
+    name: proto lint (buf)
+    runs-on: ubuntu-latest
+    # ADR 0008 PR-A1: the proto/ schema is the wire-contract source of
+    # truth for the gRPC runtime + Python / TypeScript SDKs. `buf lint`
+    # under the STANDARD ruleset enforces public-style conventions
+    # (service / message naming, enum zero-value naming, file-package
+    # alignment). `buf format --diff` enforces canonical formatting so
+    # the source of truth is also character-stable across editors.
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Install buf
+        uses: bufbuild/buf-setup-action@v1
+        with:
+          version: 1.50.0
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Lint .proto files
+        run: buf lint
+
+      - name: Verify .proto formatting is canonical
+        run: |
+          # `buf format` is an in-place rewriter; --diff makes it print
+          # what it would change instead of editing files (and always
+          # exits 0). A non-empty diff is a CI failure.
+          diff_output="$(buf format --diff)"
+          if [ -n "$diff_output" ]; then
+            echo "::error::buf format would have rewritten one or more .proto files."
+            echo "Run 'buf format -w' locally and commit the result."
+            printf '%s\n' "$diff_output"
+            exit 1
+          fi

buf.yaml

@@ -0,0 +1,27 @@
+# buf v2 workspace config — ADR 0008 PR-A1.
+#
+# v0.3 ships only a single module (the runtime schema). When PR-A2
+# and beyond add dependent schemas (e.g., a separate metrics or
+# control-plane module), additional `modules` entries land here.
+#
+# The lint policy uses buf's STANDARD set, which enforces the public-
+# style guide (file-level package matching, message naming, enum
+# zero-value naming, etc.). FILE-level breaking-change detection is
+# enabled so that any incompatible edit to a published RPC or
+# message field is caught at PR time. Until v0.3 GA the schema is
+# still flagged Unstable in §1 of ADR 0008 — breaking changes are
+# allowed, but they require an explicit ADR-update commit referencing
+# this file's diff so the audit trail is preserved.
+
+version: v2
+
+modules:
+  - path: proto
+
+lint:
+  use:
+    - STANDARD
+
+breaking:
+  use:
+    - FILE

proto/kakeya/v1/runtime.proto

@@ -0,0 +1,250 @@
+// Copyright 2026 Kakeya contributors.
+//
+// Kakeya local-agent runtime — session-bound inference protocol.
+//
+// This file is the single source of truth for the wire contract
+// between Kakeya runtime instances and their SDKs (Python and
+// TypeScript at v0.3; future Rust / Go SDKs are admitted by the
+// design but not part of v0.3 scope).
+//
+// Servers and clients MUST conform to the bytes of this schema. In
+// particular, the byte-exact KV cache binding contract (ADR 0008
+// §2.3) is parameterized over the (session_id, history_token_ids,
+// seed) triple defined here.
+//
+// References:
+//   - docs/adr/0008-session-bound-runtime-and-grpc-protocol.md
+//     - §2.1 wire protocol decision (gRPC bidi primary)
+//     - §2.2 session model (server-issued id, raw tokens, append-only)
+//     - §2.3 KV binding + determinism contract
+//     - §2.4 no chat template at the runtime, ever
+//     - §2.6 cache state lifecycle (TTL, no implicit reset)
+//     - §2.8 anomaly invariants INV-1 / INV-2 / INV-3
+//     - §2.9 observability surface
+//     - §8 OQ-2 (history > sink+window default behavior)
+//     - §8 OQ-4 (seed is per-Generate; default while unresolved)
+//
+// This is PR-A1 from ADR 0008 §6.1: schema-only landing, no code-gen
+// targets, no service implementation. The file is documentation in
+// `.proto` form. `buf lint` is the CI gate.
+
+syntax = "proto3";
+
+package kakeya.v1;
+
+// -----------------------------------------------------------------------------
+// Service
+// -----------------------------------------------------------------------------
+
+// RuntimeService is the single service exposed by a Kakeya runtime
+// instance. All session lifecycle and inference RPCs live here. v0.3
+// is single-tenant; multi-tenant authorization is deferred to v0.4
+// (ADR 0008 §4.5) and is intentionally not modeled in this schema.
+service RuntimeService {
+  // CreateSession allocates a new session and returns its server-
+  // issued identifier. Clients cannot fabricate session ids; this RPC
+  // is the only way to obtain one (ADR 0008 §2.2 contract item 1).
+  rpc CreateSession(CreateSessionRequest) returns (CreateSessionResponse);
+
+  // AppendTokens appends raw token ids to a session's history. The
+  // history is append-only within a session; clients cannot rewrite
+  // prior history mid-session (ADR 0008 §2.2 contract item 3). The
+  // server treats token ids as opaque integers and does NOT call any
+  // chat template, role marker, or template re-rendering logic
+  // (ADR 0008 §2.4).
+  rpc AppendTokens(AppendTokensRequest) returns (AppendTokensResponse);
+
+  // Generate requests up to GenerateRequest.max_tokens of generation
+  // bound to a session_id. The server streams generated token ids
+  // back as they commit (server-streaming RPC). The byte-exact KV
+  // cache binding contract (ADR 0008 §2.3) applies: for the same
+  // (session_id, history_token_ids, seed) tuple, repeated Generate
+  // calls produce bit-identical output regardless of how the history
+  // was built up (one AppendTokens of N tokens vs. N AppendTokens of
+  // 1 token vs. CreateSession+AppendTokens combinations).
+  rpc Generate(GenerateRequest) returns (stream GenerateResponse);
+
+  // CloseSession releases a session and frees its KV slab. Subsequent
+  // RPCs that reference the closed session_id return NOT_FOUND.
+  rpc CloseSession(CloseSessionRequest) returns (CloseSessionResponse);
+
+  // GetSessionInfo returns diagnostic counters for a session. Used
+  // primarily by SDK observability helpers and integration tests
+  // (ADR 0008 §2.9). Subset of the metrics also exposed on the
+  // Prometheus /metrics endpoint of the deprecated HTTP shim.
+  rpc GetSessionInfo(GetSessionInfoRequest) returns (GetSessionInfoResponse);
+}
+
+// -----------------------------------------------------------------------------
+// Session lifecycle messages
+// -----------------------------------------------------------------------------
+
+message CreateSessionRequest {
+  // Optional client-supplied label, recorded for diagnostics. Has no
+  // effect on session identity; the server still issues the
+  // session_id. Empty string = no label.
+  string client_label = 1;
+
+  // Token ids that, when emitted by the verifier sampler during
+  // Generate, cause the server to stop emitting and end the stream
+  // with GenerateDone.stop_reason = STOP_REASON_EOS. The runtime
+  // does NOT interpret these tokens semantically (ADR 0008 §2.4) —
+  // they are opaque ids supplied by the SDK / application based on
+  // its own knowledge of the model's tokenizer. Empty list =
+  // generation only stops on STOP_REASON_MAX_TOKENS, on
+  // STOP_REASON_TRUNCATED, or on cancellation.
+  repeated uint32 eos_token_ids = 2;
+}
+
+message CreateSessionResponse {
+  // Server-issued opaque identifier. Treat as a black box; do not
+  // attempt to parse, derive new ids from, or reuse across runtime
+  // process restarts.
+  string session_id = 1;
+}
+
+message AppendTokensRequest {
+  // Target session. Must reference a session previously returned by
+  // CreateSession; otherwise returns NOT_FOUND (ADR 0008 §2.6).
+  string session_id = 1;
+
+  // Raw token ids to append. Each id must be in the verifier's
+  // tokenizer vocabulary range; out-of-range ids return
+  // INVALID_ARGUMENT and the session's history is unchanged.
+  repeated uint32 token_ids = 2;
+}
+
+message AppendTokensResponse {
+  // Total number of tokens in the session's history after this
+  // append. Useful for SDK-side bookkeeping and history-length
+  // assertions.
+  uint64 history_length = 1;
+}
+
+message CloseSessionRequest {
+  string session_id = 1;
+}
+
+message CloseSessionResponse {
+  // Number of tokens that were in the session's history at close
+  // time. Diagnostic only; clients should not depend on this for
+  // correctness.
+  uint64 final_history_length = 1;
+}
+
+// -----------------------------------------------------------------------------
+// Generate messages
+// -----------------------------------------------------------------------------
+
+message GenerateRequest {
+  string session_id = 1;
+
+  // Maximum tokens to emit in this Generate call. Generation may
+  // stop earlier if (a) the verifier sampler emits one of the
+  // session's eos_token_ids (STOP_REASON_EOS), (b) the session's
+  // history would exceed the verifier's sink+window capacity
+  // (STOP_REASON_TRUNCATED, default per ADR 0008 §8 OQ-2), or
+  // (c) the call is cancelled (STOP_REASON_CANCELLED).
+  uint32 max_tokens = 2;
+
+  // Deterministic-sampling seed. ADR 0008 §8 OQ-4 default while
+  // unresolved: the seed is a per-Generate argument; the byte-exact
+  // determinism contract (§2.3) is parameterized over a fixed seed.
+  // Field is proto3-optional so the SDK can distinguish "no seed
+  // pinned, sampler may use process entropy" from "seed = 0
+  // pinned" (both are valid).
+  optional uint64 seed = 3;
+
+  // Sampling parameters, all optional. Documented here for the SDK
+  // contract; the runtime passes these through to the verifier
+  // sampler without further interpretation in v0.3.
+  optional float temperature = 4;
+  optional float top_p = 5;
+  optional uint32 top_k = 6;
+}
+
+// GenerateResponse is one frame of the server-streaming response.
+// Exactly one terminal Done event is emitted per Generate call,
+// after which the stream closes cleanly. Despite the "Response"
+// suffix (per proto3 / buf STANDARD convention), each individual
+// instance is conceptually one *event* in the stream — see the
+// `payload` oneof.
+message GenerateResponse {
+  oneof payload {
+    // A single committed token id, in the order the verifier
+    // accepted it.
+    uint32 token_id = 1;
+
+    // Terminal event. Sent exactly once at the end of the stream.
+    GenerateDone done = 2;
+
+    // History was truncated to fit within the verifier's
+    // sink+window capacity (ADR 0008 §8 OQ-2 default). Emitted at
+    // most once per Generate call, before any token_id event in
+    // that call. The truncation discards the oldest non-sink tokens;
+    // no information beyond what was discarded is recoverable.
+    HistoryTruncated truncated = 3;
+  }
+}
+
+message GenerateDone {
+  enum StopReason {
+    STOP_REASON_UNSPECIFIED = 0;
+    STOP_REASON_MAX_TOKENS = 1;
+    STOP_REASON_EOS = 2;
+    STOP_REASON_CANCELLED = 3;
+    STOP_REASON_TRUNCATED = 4;
+  }
+  StopReason stop_reason = 1;
+
+  // Number of tokens this Generate call appended to the session
+  // history (excludes the prefill phase).
+  uint32 generated_token_count = 2;
+
+  // Wall-clock duration of the prefill phase for this call, in
+  // seconds. Exposes the §2.9 metric `generate_prefill_duration_seconds`
+  // observation that this call contributed.
+  double prefill_duration_seconds = 3;
+
+  // Wall-clock duration from prefill start to last token committed.
+  double total_duration_seconds = 4;
+}
+
+message HistoryTruncated {
+  // Number of tokens dropped from the history. The verifier slab
+  // now holds (sink + window) tokens at most; this event reports
+  // history_length - (sink + window) at the moment of truncation.
+  uint64 dropped_token_count = 1;
+}
+
+// -----------------------------------------------------------------------------
+// Diagnostic messages
+// -----------------------------------------------------------------------------
+
+message GetSessionInfoRequest {
+  string session_id = 1;
+}
+
+message GetSessionInfoResponse {
+  // Number of tokens currently in the session's history (after any
+  // truncation; the runtime never reports a history longer than the
+  // slab can hold).
+  uint64 history_length = 1;
+
+  // Live KV bytes held by the session's slab. Sum of all sessions'
+  // values equals the §2.9 `session_kv_live_bytes` gauge.
+  uint64 kv_live_bytes = 2;
+
+  // Anomaly-invariant violation counters per ADR 0008 §2.8. MUST be
+  // 0 under healthy operation. Non-zero is a paging-grade signal
+  // that the session has been failed and the slab freed; the
+  // session_id is no longer usable for AppendTokens / Generate
+  // (those return NOT_FOUND or FAILED_PRECONDITION).
+  uint64 cache_invariant_inv1_violations = 3;
+  uint64 cache_invariant_inv2_violations = 4;
+
+  // Wall-clock seconds since this session's last RPC interaction.
+  // The runtime evicts sessions idle longer than its configured
+  // session_idle_ttl_s (ADR 0008 §2.6 default 1800s).
+  double idle_seconds = 5;
+}