feat: meta support

Author: skosovsky

README.md

@@ -4,7 +4,7 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/skosovsky/contexty)](https://goreportcard.com/report/github.com/skosovsky/contexty)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-`contexty` is a **semantic context engine** for LLM applications: typed message AST, segment-based `ConversationStore`, non-mutating views, unified budgeting, and `Compile()` → `AbstractPayload`.
+`contexty` is a **semantic context engine** for LLM applications: typed message AST, segment-based `ConversationStore`, non-mutating views, unified budgeting, and `Compile()` → `CompileResult` (payload + transformations by `Message.ID`).
 
 ## Installation
 
@@ -37,11 +37,13 @@ engine := contexty.NewEngine(
     )),
 )
 
-payload, err := engine.Compile(ctx)
-_ = payload.FlattenMessages()
+	result, err := engine.Compile(ctx, contexty.CompileRequest{
+		Pending: []contexty.Message{contexty.TextMessage(contexty.RoleUser, "Current turn")},
+	})
+	_ = result.Payload.FlattenMessages()
 ```
 
-See [Developer Guide](docs/developer-guide.md) and [ADR-001](docs/adr/001-semantic-context-engine.md).
+See [Developer Guide](docs/developer-guide.md), [ADR-001](docs/adr/001-semantic-context-engine.md), and [ADR-002](docs/adr/002-clear-break-compile-contract.md).
 
 ## Views (non-mutating render)
 

adapters/store/postgres/store_integration_test.go

@@ -296,12 +296,14 @@ func expandedSystemMessage() contexty.Message {
 func expandedHistoryMessage() contexty.Message {
 	ts := time.Date(2025, 6, 2, 9, 0, 0, 0, time.UTC)
 	return contexty.Message{
+		ID:   "msg-expanded-hist",
 		Role: contexty.RoleUser,
 		Parts: []contexty.ContentPart{
 			contexty.TextPart{Text: "see image"},
 			contexty.ImagePart{URL: "https://example.com/a.png", Detail: "low"},
 		},
 		Annotations: contexty.Annotations{Timestamp: &ts, RefID: "img-1"},
+		Attributes:  contexty.Attributes{"tier": "premium", "count": float64(2)},
 		Provenance:  contexty.UserProvenance{Channel: "web", UserID: "u2"},
 	}
 }
@@ -319,6 +321,9 @@ func assertExpandedSemanticRoundTrip(t *testing.T, ctx context.Context, store *S
 
 	history := snap.Segment(contexty.SegmentHistory)
 	require.Len(t, history, 1)
+	assert.Equal(t, "msg-expanded-hist", history[0].ID)
+	assert.Equal(t, "premium", history[0].Attributes["tier"])
+	assert.InEpsilon(t, float64(2), history[0].Attributes["count"], 0)
 	require.Len(t, history[0].Parts, 2)
 	_, hasImage := history[0].Parts[1].(contexty.ImagePart)
 	require.True(t, hasImage)

adapters/store/redis/store_integration_test.go

@@ -243,12 +243,14 @@ func expandedSystemMessage() contexty.Message {
 func expandedHistoryMessage() contexty.Message {
 	ts := time.Date(2025, 6, 2, 9, 0, 0, 0, time.UTC)
 	return contexty.Message{
+		ID:   "msg-expanded-hist",
 		Role: contexty.RoleUser,
 		Parts: []contexty.ContentPart{
 			contexty.TextPart{Text: "see image"},
 			contexty.ImagePart{URL: "https://example.com/a.png", Detail: "low"},
 		},
 		Annotations: contexty.Annotations{Timestamp: &ts, RefID: "img-1"},
+		Attributes:  contexty.Attributes{"tier": "premium", "count": float64(2)},
 		Provenance:  contexty.UserProvenance{Channel: "web", UserID: "u2"},
 	}
 }
@@ -266,6 +268,9 @@ func assertExpandedSemanticRoundTrip(t *testing.T, ctx context.Context, store *S
 
 	history := snap.Segment(contexty.SegmentHistory)
 	require.Len(t, history, 1)
+	assert.Equal(t, "msg-expanded-hist", history[0].ID)
+	assert.Equal(t, "premium", history[0].Attributes["tier"])
+	assert.InEpsilon(t, float64(2), history[0].Attributes["count"], 0)
 	require.Len(t, history[0].Parts, 2)
 	_, hasImage := history[0].Parts[1].(contexty.ImagePart)
 	require.True(t, hasImage)

architecture_test.go

@@ -38,6 +38,23 @@ func TestArchitecture_NoForbiddenExternalImports(t *testing.T) {
 	}
 }
 
+func TestArchitecture_NoJSONMetadataInTextParts(t *testing.T) {
+	root, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+	violations, err := findJSONMetadataInTextViolations(root)
+	if err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+	if len(violations) > 0 {
+		t.Fatalf(
+			"json metadata tunneling via TextContent forbidden in semantic core:\n%s",
+			strings.Join(violations, "\n"),
+		)
+	}
+}
+
 func TestArchitecture_NoBase64InCore(t *testing.T) {
 	root, err := os.Getwd()
 	if err != nil {
@@ -93,13 +110,84 @@ func isArchitectureSourceFile(path string) bool {
 
 func isArchitectureAllowlisted(path string) bool {
 	switch filepath.Base(path) {
-	case "transform.go", "views.go", "model.go":
+	case "transform.go", "views.go", "model.go", "provenance.go", "serializer.go", "content_part.go":
 		return true
 	default:
 		return false
 	}
 }
 
+func findJSONMetadataInTextViolations(root string) ([]string, error) {
+	fset := token.NewFileSet()
+	var violations []string
+	err := filepath.Walk(root, func(path string, info os.FileInfo, walkErr error) error {
+		if walkErr != nil {
+			return walkErr
+		}
+		if info.IsDir() {
+			if shouldSkipArchitectureDir(filepath.Base(path)) {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if !isArchitectureSourceFile(path) || isArchitectureAllowlisted(path) {
+			return nil
+		}
+		file, parseErr := parser.ParseFile(fset, path, nil, 0)
+		if parseErr != nil {
+			return parseErr
+		}
+		violations = append(violations, collectJSONMetadataInTextViolations(fset, file)...)
+		return nil
+	})
+	return violations, err
+}
+
+func collectJSONMetadataInTextViolations(fset *token.FileSet, file *ast.File) []string {
+	var violations []string
+	ast.Inspect(file, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok || len(call.Args) == 0 {
+			return true
+		}
+		if !isJSONUnmarshalCall(call) {
+			return true
+		}
+		if !exprReferencesTextContent(call.Args[0]) {
+			return true
+		}
+		pos := fset.Position(call.Pos())
+		violations = append(violations, pos.String())
+		return true
+	})
+	return violations
+}
+
+func isJSONUnmarshalCall(call *ast.CallExpr) bool {
+	sel, ok := call.Fun.(*ast.SelectorExpr)
+	if !ok {
+		return false
+	}
+	pkg, ok := sel.X.(*ast.Ident)
+	return ok && pkg.Name == "json" && sel.Sel.Name == "Unmarshal"
+}
+
+func exprReferencesTextContent(expr ast.Expr) bool {
+	found := false
+	ast.Inspect(expr, func(n ast.Node) bool {
+		sel, ok := n.(*ast.SelectorExpr)
+		if !ok {
+			return true
+		}
+		if sel.Sel.Name == "TextContent" {
+			found = true
+			return false
+		}
+		return true
+	})
+	return found
+}
+
 func collectStringHeuristicCalls(fset *token.FileSet, file *ast.File) []string {
 	var violations []string
 	ast.Inspect(file, func(n ast.Node) bool {

attributes.go

@@ -0,0 +1,16 @@
+package contexty
+
+import "maps"
+
+// Attributes holds host-controlled metadata separate from Provenance (source URI/ID).
+type Attributes map[string]any
+
+// Clone returns a deep copy of attributes (shallow copy of map values).
+func (a Attributes) Clone() Attributes {
+	if len(a) == 0 {
+		return nil
+	}
+	out := make(Attributes, len(a))
+	maps.Copy(out, a)
+	return out
+}