docs: add changelog for go-v0.2.1

[sergiught]

Description

Adds the changelog for go-v0.2.1

References

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

• New Features

  • Added comprehensive validation logic for write relations and write tuples
  • Introduced locking and edge/weight handling for UserSet constructs
  • Expanded relation edge definitions and character allowances for names
  • Implemented edge deduplication with conditional support

• Bug Fixes

  • Fixed recursive nested tuple cycle issues
  • Resolved weight assignment and exclusion scenario problems

[coderabbitai]

Walkthrough

A changelog update that introduces a new v0.2.1 release entry dated 2026-03-25, documenting additions for validation and edge/weight handling, changes to relation definitions and character allowances, and fixes for recursive tuple cycles and weight scenarios.

Changes

Cohort / File(s)	Summary
Changelog pkg/go/CHANGELOG.md	Added v0.2.1 release section with enumerated items covering new validation logic for write relations/tuples, locking and edge/weight handling for UserSet constructs, relation edge definition updates, name character allowances, edge deduplication logic, and fixes for recursive nested tuple cycles and weight assignment/exclusion edge cases.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested reviewers

• SoulPancake

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and directly describes the main change: adding a changelog entry for go-v0.2.1, which matches the file updated (pkg/go/CHANGELOG.md).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch release/go-v0.2.1

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[dosubot]

Documentation Updates

1 document(s) were updated by changes in this PR:

Authorization Model Graph and Weighted Graph

View Changes

@@ -23,7 +23,7 @@
 The `GetDirectEdgesAssignation(node)` method traverses the graph to collect all direct edges for a given relation node, handling cases where direct assignments are grouped under logical nodes or nested within set operations. This ensures that write validation is accurate, even for complex relation definitions involving logical grouping or set operations.
 
 - **Direct assignment tracking**: When a relation is defined with direct assignments (e.g., `viewer: [user, employee]`), the graph records these assignments for fast validation.
-- **Write validation**: Before allowing a tuple write, the system checks if the assignment is present in the node's `directAssigns` or can be resolved via direct edges using `GetDirectEdgesAssignation`.
+- **Write validation**: Before allowing a tuple write, the system validates both the write tuple itself and the write relation between a node and a UserType. The system checks if the assignment is present in the node's `directAssigns` or can be resolved via direct edges using `GetDirectEdgesAssignation`.
 
 This mechanism guarantees that only valid tuples, as defined by the model's direct assignment rules, can be written, improving both correctness and security.
 
@@ -37,10 +37,10 @@
 - **DirectLogicalEdge**: Groups multiple direct assignments under a logical node.
 - **TTULogicalEdge**: Groups multiple TTU edges under a logical node.
 
-Logical grouping nodes (LogicalDirectGrouping and LogicalTTUGrouping) are introduced when a relation has multiple direct assignments or TTU edges. For example, if a relation is defined as `viewer: [user, employee]`, a LogicalDirectGrouping node clusters the direct edges to `user` and `employee`. This grouping clarifies the graph structure and enables efficient query planning [[source]](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph_builder.go#L14-L216).
+Logical grouping nodes (LogicalDirectGrouping and LogicalTTUGrouping) are introduced when a relation has multiple direct assignments or TTU edges. For example, if a relation is defined as `viewer: [user, employee]`, a LogicalDirectGrouping node clusters the direct edges to `user` and `employee`. This grouping clarifies the graph structure and enables efficient query planning. All edges now include their relation definitions, and edges are deduplicated when conditions exist, with conditions added to the deduplicated edges [[source]](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph_builder.go#L14-L216).
 
 #### Graph Construction
-Graph construction involves parsing the authorization model, adding nodes and edges for each type and relation, and grouping related edges under logical nodes when multiple related types exist. The builder sorts types and relations for stable output, creates nodes for each type and relation, and adds edges with associated metadata. After construction, the graph assigns weights to nodes and edges to represent traversal costs or distances [[source]](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph_builder.go#L14-L216).
+Graph construction involves parsing the authorization model, adding nodes and edges for each type and relation, and grouping related edges under logical nodes when multiple related types exist. The builder supports '/' and '.' in type and relation names, sorts types and relations for stable output, creates nodes for each type and relation, and adds edges with associated metadata. After construction, the graph assigns weights to nodes and edges to represent traversal costs or distances [[source]](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph_builder.go#L14-L216).
 
 #### Edge Metadata
 Edges in the weighted graph carry metadata including:
@@ -51,13 +51,14 @@
 - **Conditions** (for conditional assignments)
 - **Weights** (per userset key)
 - **Recursive relation and tuple cycle flags**
+- **Relation definition** (available for all edges)
 
-This metadata is used for edge uniqueness, condition management, and traversal optimization. For example, conditions allow the graph to represent both unconditional and conditional assignments between the same nodes, while weights enable the query planner to select the most efficient traversal path [[source]](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph.go#L18-L1134).
+This metadata is used for edge uniqueness, condition management, and traversal optimization. For example, conditions allow the graph to represent both unconditional and conditional assignments between the same nodes, while weights (including UserSet weights that can be associated with edges) enable the query planner to select the most efficient traversal path. Locking mechanisms ensure thread-safe UserSet weight writes [[source]](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph.go#L18-L1134).
 
 #### Recursive Cycles and Tuple Cycles
-**Recursive cycles** occur when a relation is defined in terms of itself, either directly or through a chain of rewrites (e.g., `parent: parent from parent`). These are detected as self-loops in the graph. When detected, the corresponding edge is assigned an infinite weight and marked with recursiveRelation metadata, ensuring that query planners do not recurse infinitely [[source]](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph.go#L18-L1134).
+**Recursive cycles** occur when a relation is defined in terms of itself, either directly or through a chain of rewrites (e.g., `parent: parent from parent`). These are detected as self-loops in the graph. When detected, the corresponding edge is assigned an infinite weight and marked with recursiveRelation metadata, ensuring that query planners do not recurse infinitely. The system differentiates between recursive cycles and tuple cycles to handle each appropriately [[source]](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph.go#L18-L1134).
 
-**Tuple cycles** arise when a chain of TTU or direct edges forms a cycle involving type-relation nodes. The graph detects tuple cycles by analyzing ancestor paths during weight assignment. Tuple cycles are marked with tupleCycle metadata and handled with special weight assignment and dependency resolution, allowing the planner to resolve them safely without infinite recursion [[source]](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph.go#L18-L1134).
+**Tuple cycles** arise when a chain of TTU or direct edges forms a cycle involving type-relation nodes. The graph detects tuple cycles by analyzing ancestor paths during weight assignment. Tuple cycles are marked with tupleCycle metadata and handled with special weight assignment and dependency resolution, allowing the planner to resolve them safely without infinite recursion. Handling for recursive nested tuple cycle assignments has been improved to ensure correctness [[source]](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph.go#L18-L1134).
 
 Cycle detection distinguishes between:
 
@@ -68,12 +69,12 @@
 #### Performance and Correctness Improvements
 The weighted graph structure, with its logical grouping nodes, edge metadata, and weight assignment, enables several key optimizations:
 
-- **Efficient query planning**: Weights guide the planner to the shortest or most efficient resolution path.
+- **Efficient query planning**: Weights guide the planner to the shortest or most efficient resolution path. Weight calculations have been improved to correctly assign weights for intersections with multiple direct types and for exclusion operations where a type is not in the excluded relation.
 - **Edge pruning**: Edges that cannot lead to a userset are pruned early, reducing unnecessary computation.
 - **Fast-path resolvers**: The planner can use optimized algorithms (e.g., weight-2 or recursive resolvers) when the graph structure allows.
 - **Cycle safety**: Recursive and tuple cycles are detected and handled, preventing infinite recursion and ensuring valid model semantics [[source]](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph.go#L18-L1134).
 
-These structures underpin the correctness and performance of OpenFGA's authorization resolution, especially for complex models with nested rewrites and cycles.
+These structures underpin the correctness and performance of OpenFGA's authorization resolution, especially for complex models with nested rewrites and cycles. These capabilities reflect improvements introduced in pkg/go v0.2.1 (released 2026-03-25).
 
 #### Example: Logical Grouping and Cycle Detection
 Consider the following model:
@@ -109,4 +110,5 @@
 
 ---
 
-For further details, see the [OpenFGA weighted graph implementation](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph.go#L18-L1134) and [graph builder logic](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph_builder.go#L14-L216).
+For further details, see the [OpenFGA weighted graph implementation](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph.go#L18-L1134), [graph builder logic](https://github.com/openfga/language/blob/e4d9ef4161485085d22789c602a1004525622f46/pkg/go/graph/weighted_graph_builder.go#L14-L216), and [pkg/go v0.2.1 changelog](https://github.com/openfga/language/blob/main/pkg/go/CHANGELOG.md#pkgov021).
+

^{How did I do? Any feedback?}  

[Copilot]

Pull request overview

Adds the changelog entry for the Go package release pkg/go/v0.2.1, aligning the Go package documentation with existing release-note patterns in the repo.

Changes:

• Add an “Unreleased” section with a compare link against pkg/go/v0.2.1.
• Add release notes for pkg/go/v0.2.1 (Added/Changed/Fixed lists) and its release date.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@pkg/go/CHANGELOG.md`:
- Line 26: Replace the typo in the changelog entry that reads "Recursive nested
tuple cycles assignations (`#497`)" by changing "assignations" to the standard
term "assignments"; update that exact string in pkg/go/CHANGELOG.md so the line
reads "Recursive nested tuple cycles assignments (`#497`)" to correct wording.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cffe2bfc-b828-430d-a59e-24269e6684b9

📥 Commits

Reviewing files that changed from the base of the PR and between c7c7efd and edfcf49.

📒 Files selected for processing (1)

• pkg/go/CHANGELOG.md