feat(release): v8.5.0 — decision request context + pasal_56b_dpa transfer basis

Targets AxonFlow platform v8.5.0 (epic #2508).

- DecisionSummary + DecisionExplanation gain a Context map[string]string
  (json:"context,omitempty") surfacing the sanitized request context a PEP
  attaches to a Decision Mode call (platform #2509). ListDecisions returns the
  platform-truncated 5-key summary; ExplainDecision returns the full map plus a
  ContextTruncated bool.
- ojk.go adds TransferBasis* constants (adequacy, safeguards, pasal_56b_dpa,
  consent) for type-safe access to the UU PDP Pasal 56 legal bases. The
  AuditLogEntry/CrossBorderTransferRecord TransferBasis field stays a plain
  string surfaced verbatim, so existing 'safeguards' consumers are unaffected.
- version 8.3.0 -> 8.5.0, CHANGELOG entry, unit tests, and a runtime-e2e driver
  that creates a decision via the PEP path and reads Context back through the SDK.

Signed-off-by: Saurabh Jain <saurabh.jain@getaxonflow.com>

Author: saurabhjain1592

CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to the AxonFlow Go SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.5.0] - 2026-05-30 — Decision request context + Pasal 56(b) transfer basis
+
+Targets AxonFlow platform **v8.5.0**.
+
+### Added
+
+- **`Context` field on `DecisionSummary` and `DecisionExplanation`** — `map[string]string`,
+  `json:"context,omitempty"`. Surfaces the sanitized request context a PEP attaches to a
+  Decision Mode call (canonical `lower_snake_case` keys such as `x_ai_agent`, `x_session_id`,
+  `x_leader_identity`, and `x-bukuwarung-*`), persisted by the platform at the audit row's
+  `policy_details->'context'`. `ListDecisions` returns the platform-truncated summary (the 5
+  most-correlated keys); `ExplainDecision` returns the full map up to the platform's 10-key cap.
+- **`ContextTruncated` field on `DecisionExplanation`** — `bool`, `json:"context_truncated,omitempty"`.
+  Reports whether the agent dropped surplus context keys at write time.
+- **`TransferBasis*` constants** (`ojk.go`): `TransferBasisAdequacy`, `TransferBasisSafeguards`,
+  `TransferBasisPasal56bDPA` (`"pasal_56b_dpa"`), `TransferBasisConsent`. Type-safe access to the
+  Indonesia UU PDP Pasal 56 legal bases recognized for the `TransferBasis` field on
+  `CrossBorderTransferRecord` and `AuditLogEntry`.
+
+### Changed
+
+- **`AuditLogEntry.TransferBasis` documentation** now records `pasal_56b_dpa` (Pasal 56(b) explicit
+  DPA tag) as an accepted value alongside `adequacy`, `safeguards`, and `consent`. The field stays a
+  plain `string` (surfaced verbatim), so existing code switching on `safeguards` is unaffected and the
+  SDK never rejects a value a newer platform may add.
+
 ## [8.3.0] - 2026-05-27 — Indonesia PII category + cross-border audit fields + OJK types
 
 ### Added

audit.go

@@ -91,7 +91,10 @@ type AuditLogEntry struct {
 	Metadata map[string]interface{} `json:"metadata,omitempty"`
 	// DataResidency is the ISO 3166-1 alpha-2 country code where data is stored
 	DataResidency string `json:"data_residency,omitempty"`
-	// TransferBasis is the legal basis for cross-border data transfer: adequacy, safeguards, or consent
+	// TransferBasis is the legal basis for cross-border data transfer under
+	// Indonesia UU PDP Pasal 56: adequacy, safeguards, pasal_56b_dpa, or consent.
+	// Surfaced verbatim — see the TransferBasis* constants in ojk.go for the
+	// recognized set and their Pasal 56 mapping.
 	TransferBasis string `json:"transfer_basis,omitempty"`
 }
 

audit_test.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 	"time"
 )
@@ -1000,6 +1001,41 @@ func TestAuditLogEntryCrossBorderFields(t *testing.T) {
 		}
 	})
 
+	t.Run("pasal_56b_dpa transfer basis (v8.5.0)", func(t *testing.T) {
+		jsonData := `{
+			"id": "aud-56b",
+			"timestamp": "2026-05-30T10:00:00Z",
+			"data_residency": "ID",
+			"transfer_basis": "pasal_56b_dpa"
+		}`
+		var entry AuditLogEntry
+		if err := json.Unmarshal([]byte(jsonData), &entry); err != nil {
+			t.Fatalf("unmarshal: %v", err)
+		}
+		if entry.TransferBasis != TransferBasisPasal56bDPA {
+			t.Errorf("transfer_basis = %q, want %q", entry.TransferBasis, TransferBasisPasal56bDPA)
+		}
+		// Round-trips verbatim — never auto-translated to "safeguards".
+		out, err := json.Marshal(entry)
+		if err != nil {
+			t.Fatalf("marshal: %v", err)
+		}
+		if !strings.Contains(string(out), `"transfer_basis":"pasal_56b_dpa"`) {
+			t.Errorf("expected pasal_56b_dpa verbatim on the wire: %s", out)
+		}
+	})
+
+	t.Run("backward compat - safeguards still parses (v8.5.0 widening)", func(t *testing.T) {
+		jsonData := `{"id":"aud-sg","timestamp":"2026-05-26T10:00:00Z","transfer_basis":"safeguards"}`
+		var entry AuditLogEntry
+		if err := json.Unmarshal([]byte(jsonData), &entry); err != nil {
+			t.Fatalf("unmarshal: %v", err)
+		}
+		if entry.TransferBasis != TransferBasisSafeguards {
+			t.Errorf("transfer_basis = %q, want safeguards", entry.TransferBasis)
+		}
+	})
+
 	t.Run("backward compat - fields absent", func(t *testing.T) {
 		jsonData := `{
 			"id": "aud-002",

decisions.go

@@ -34,6 +34,18 @@ type DecisionExplanation struct {
 	HistoricalHitCountSession int             `json:"historical_hit_count_session"`
 	PolicySourceLink          string          `json:"policy_source_link,omitempty"`
 	ToolSignature             string          `json:"tool_signature,omitempty"`
+
+	// Context is the FULL sanitized request context the PEP attached to the
+	// decision (canonical lower_snake_case keys, string values), read from
+	// the audit row's policy_details->'context'. Unlike ListDecisions (which
+	// truncates to the 5 most-correlated keys), Explain returns every
+	// persisted key up to the platform's 10-key cap, so an auditor gets the
+	// complete correlation set (x_ai_agent / x_session_id / x_leader_identity,
+	// x-bukuwarung-*). ContextTruncated reports whether the agent dropped
+	// surplus keys at write time. Both omitempty so pre-v8.5.0 audit rows keep
+	// their original byte-shape. (platform #2509 / epic #2508)
+	Context          map[string]string `json:"context,omitempty"`
+	ContextTruncated bool              `json:"context_truncated,omitempty"`
 }
 
 // ExplainPolicy is a policy reference inside an explanation.
@@ -137,6 +149,15 @@ type DecisionSummary struct {
 	Decision      string    `json:"decision"` // "allow"|"deny"|"require_approval"
 	PolicyID      string    `json:"policy_id,omitempty"`
 	ToolSignature string    `json:"tool_signature,omitempty"`
+
+	// Context is the sanitized request context the PEP attached to the
+	// decision (canonical lower_snake_case keys, string values), surfaced
+	// from the audit row's policy_details->'context'. The list summary is
+	// truncated by the platform to the 5 most-correlated keys; the full map
+	// (up to the 10-key cap) is available via ExplainDecision. omitempty so
+	// pre-v8.5.0 audit rows + decisions with no context keep the original
+	// byte-shape. (platform #2509 / epic #2508)
+	Context map[string]string `json:"context,omitempty"`
 }
 
 // ListDecisionsOptions carries the 5 optional filters for ListDecisions.

decisions_test.go

@@ -428,3 +428,91 @@ func TestDecisionSummary_OptionalFieldsRoundTrip(t *testing.T) {
 		t.Errorf("omitempty must drop unset optionals: %s", s)
 	}
 }
+
+// TestDecisionSummary_ContextRoundTrip — v8.5.0 (platform #2509): the LIST
+// row carries the sanitized request context the PEP attached to the decision.
+// The map must parse and re-serialize without information loss.
+func TestDecisionSummary_ContextRoundTrip(t *testing.T) {
+	raw := []byte(`{"decision_id":"dec-ctx","timestamp":"2026-05-30T12:00:00Z","decision":"deny",` +
+		`"context":{"x_ai_agent":"refund-bot","x_session_id":"sess-42","x_leader_identity":"ops-lead"}}`)
+	var d DecisionSummary
+	if err := json.Unmarshal(raw, &d); err != nil {
+		t.Fatal(err)
+	}
+	if len(d.Context) != 3 {
+		t.Fatalf("expected 3 context keys, got %d (%+v)", len(d.Context), d.Context)
+	}
+	if d.Context["x_ai_agent"] != "refund-bot" || d.Context["x_session_id"] != "sess-42" {
+		t.Errorf("context values not preserved: %+v", d.Context)
+	}
+	out, err := json.Marshal(d)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var back DecisionSummary
+	if err := json.Unmarshal(out, &back); err != nil {
+		t.Fatal(err)
+	}
+	if back.Context["x_leader_identity"] != "ops-lead" {
+		t.Errorf("round-trip lost context: %s", out)
+	}
+}
+
+// TestDecisionSummary_ContextOmittedWhenEmpty — a decision with no request
+// context (or a pre-v8.5.0 audit row) must keep its original byte-shape:
+// omitempty drops the absent map so the wire payload is unchanged.
+func TestDecisionSummary_ContextOmittedWhenEmpty(t *testing.T) {
+	raw := []byte(`{"decision_id":"dec-noctx","timestamp":"2026-05-30T12:00:00Z","decision":"allow"}`)
+	var d DecisionSummary
+	if err := json.Unmarshal(raw, &d); err != nil {
+		t.Fatal(err)
+	}
+	if d.Context != nil {
+		t.Errorf("expected nil context, got %+v", d.Context)
+	}
+	out, err := json.Marshal(d)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(out), "context") {
+		t.Errorf("omitempty must drop unset context: %s", out)
+	}
+}
+
+// TestDecisionExplanation_ContextAndTruncated — v8.5.0 (platform #2509): the
+// explain payload returns the FULL context map plus the context_truncated flag.
+func TestDecisionExplanation_ContextAndTruncated(t *testing.T) {
+	raw := []byte(`{"decision_id":"dec-x","timestamp":"2026-05-30T12:00:00Z","decision":"deny",` +
+		`"reason":"pii","override_available":false,"historical_hit_count_session":0,` +
+		`"policy_matches":[],"context":{"x_ai_agent":"a","x_session_id":"s"},"context_truncated":true}`)
+	var e DecisionExplanation
+	if err := json.Unmarshal(raw, &e); err != nil {
+		t.Fatal(err)
+	}
+	if len(e.Context) != 2 || e.Context["x_ai_agent"] != "a" {
+		t.Errorf("explain context not parsed: %+v", e.Context)
+	}
+	if !e.ContextTruncated {
+		t.Errorf("expected context_truncated=true")
+	}
+	out, err := json.Marshal(e)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(out), `"context_truncated":true`) {
+		t.Errorf("context_truncated must serialize when true: %s", out)
+	}
+}
+
+// TestDecisionExplanation_ContextTruncatedOmittedWhenFalse — the common case
+// (nothing dropped) must not emit context_truncated, preserving byte-shape.
+func TestDecisionExplanation_ContextTruncatedOmittedWhenFalse(t *testing.T) {
+	e := DecisionExplanation{DecisionID: "d", Decision: "allow"}
+	out, err := json.Marshal(e)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(out), "context_truncated") {
+		t.Errorf("omitempty must drop context_truncated when false: %s", out)
+	}
+}

ojk.go

@@ -77,3 +77,24 @@ type CrossBorderTransferRecord struct {
 	Purpose         string    `json:"purpose,omitempty"`
 	Status          string    `json:"status"`
 }
+
+// Cross-border transfer-basis values recognized under Indonesia UU PDP Pasal 56.
+// These are the legal bases the platform accepts for the TransferBasis field on
+// CrossBorderTransferRecord and AuditLogEntry. The field remains a plain string
+// so the SDK never rejects a value a newer platform may add; these constants give
+// callers type-safe access to the known set.
+//
+//   - TransferBasisAdequacy    → Pasal 56(a): destination with adequate protection
+//   - TransferBasisSafeguards  → Pasal 56(b): binding legal instrument (generic label)
+//   - TransferBasisPasal56bDPA → Pasal 56(b): binding legal instrument, explicit DPA tag
+//   - TransferBasisConsent     → Pasal 56(c): explicit data-subject consent
+//
+// "safeguards" and "pasal_56b_dpa" are semantic equivalents; both are surfaced
+// verbatim and never auto-translated, so an auditor sees the value recorded at
+// decision time. (platform #2513 / epic #2508)
+const (
+	TransferBasisAdequacy    = "adequacy"
+	TransferBasisSafeguards  = "safeguards"
+	TransferBasisPasal56bDPA = "pasal_56b_dpa"
+	TransferBasisConsent     = "consent"
+)

ojk_test.go

@@ -2,6 +2,7 @@ package axonflow
 
 import (
 	"encoding/json"
+	"strings"
 	"testing"
 	"time"
 )
@@ -198,6 +199,63 @@ func TestCrossBorderTransferRecordOmitsEmpty(t *testing.T) {
 	}
 }
 
+// TestTransferBasisConstants pins the wire values of the UU PDP Pasal 56
+// transfer-basis constants added in v8.5.0 (platform #2513).
+func TestTransferBasisConstants(t *testing.T) {
+	cases := map[string]string{
+		TransferBasisAdequacy:    "adequacy",
+		TransferBasisSafeguards:  "safeguards",
+		TransferBasisPasal56bDPA: "pasal_56b_dpa",
+		TransferBasisConsent:     "consent",
+	}
+	for got, want := range cases {
+		if got != want {
+			t.Errorf("transfer-basis constant = %q, want %q", got, want)
+		}
+	}
+}
+
+// TestCrossBorderTransferRecord_Pasal56bDPA — the new Pasal 56(b) explicit DPA
+// tag must round-trip on CrossBorderTransferRecord without information loss.
+func TestCrossBorderTransferRecord_Pasal56bDPA(t *testing.T) {
+	record := CrossBorderTransferRecord{
+		ID:            "xfer-56b",
+		SourceCountry: "ID",
+		DestCountry:   "SG",
+		TransferBasis: TransferBasisPasal56bDPA,
+		TransferDate:  time.Now().Truncate(time.Second),
+		Status:        "approved",
+	}
+	data, err := json.Marshal(record)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if !strings.Contains(string(data), `"transfer_basis":"pasal_56b_dpa"`) {
+		t.Errorf("expected pasal_56b_dpa on the wire: %s", data)
+	}
+	var decoded CrossBorderTransferRecord
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if decoded.TransferBasis != "pasal_56b_dpa" {
+		t.Errorf("transfer_basis = %q, want pasal_56b_dpa", decoded.TransferBasis)
+	}
+}
+
+// TestTransferBasis_BackwardCompatSafeguards — existing v8.3.0-shaped records
+// using "safeguards" must continue to parse unchanged after the widening.
+func TestTransferBasis_BackwardCompatSafeguards(t *testing.T) {
+	raw := []byte(`{"id":"xfer-old","source_country":"ID","dest_country":"NL",` +
+		`"transfer_basis":"safeguards","transfer_date":"2026-05-26T00:00:00Z","status":"approved"}`)
+	var decoded CrossBorderTransferRecord
+	if err := json.Unmarshal(raw, &decoded); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if decoded.TransferBasis != TransferBasisSafeguards {
+		t.Errorf("transfer_basis = %q, want safeguards", decoded.TransferBasis)
+	}
+}
+
 func TestOJKAuditExportRoundTrip(t *testing.T) {
 	now := time.Now().Truncate(time.Second)
 	req := OJKAuditExportRequest{

runtime-e2e/decision_context_transfer_basis/README.md

@@ -0,0 +1,27 @@
+# decision_context_transfer_basis (v8.5.0)
+
+Real-wire test for the v8.5.0 SDK surface (platform epic #2508):
+
+- **`DecisionSummary.Context` / `DecisionExplanation.Context`** — the sanitized
+  request context a PEP attaches to a Decision Mode call is surfaced back
+  through `ListDecisions` and `ExplainDecision`.
+- **`AuditLogEntry.TransferBasis = "pasal_56b_dpa"`** — the Pasal 56(b) explicit
+  DPA tag round-trips verbatim.
+
+The driver acts as the PEP (raw `POST /api/v1/decide` — that endpoint is
+intentionally not SDK-wrapped per ADR-056), then reads the decision back through
+the SDK and asserts `Context` is populated with the PEP-forwarded keys.
+
+## Run
+
+```
+# Requires a running agent at AXONFLOW_AGENT_URL (default http://localhost:8080).
+# In community mode any client id/secret is accepted and maps to a tenant.
+export AXONFLOW_AGENT_URL=http://localhost:8080
+export AXONFLOW_TENANT_ID=buku-e-go-e2e
+export AXONFLOW_TENANT_SECRET=buku-e-secret
+
+go run runtime-e2e/decision_context_transfer_basis/main.go
+```
+
+Exits non-zero if the SDK does not surface the new fields.