Add Clerk tutorial

[JulienLavocat]

Description of Changes

Add Clerk tutorial

API and ABI breaking changes

None.

Expected complexity level and risk

1

Testing

Tested locally

[JulienLavocat]

/update-llm-benchmark

[clockwork-labs-bot]

LLM Benchmark Results (ci-quickfix)

Language	Mode	Category	Tests Passed	Task Pass %
Rust	rustdoc_json	basics	26/27	91.7% ⬆️ +8.3%
Rust	rustdoc_json	schema	29/34	80.0%
Rust	rustdoc_json	total	55/61	86.4% ⬆️ +4.5%
C#	docs	basics	11/27	59.0% ⬇️ -2.1%
C#	docs	schema	10/34	31.5%
C#	docs	total	21/61	46.5% ⬇️ -1.1%

Compared against master branch baseline

_{Generated at: 2026-01-20T12:13:28.082Z}

Failure Analysis (click to expand)

Benchmark Failure Analysis

Generated from: /__w/SpacetimeDB/SpacetimeDB/tools/xtask-llm-benchmark/../../docs/llms/docs-benchmark-details.json

Summary

• Total failures analyzed: 22

Analysis

Analysis of SpacetimeDB Benchmark Failures

Rust Failures

1. Root Causes

• Compile/Publish Errors:

  • The errors publish_error: spacetime publish failed (exit=1) indicate issues related to improperly defined packages or dependencies during the publish phase.
  • Example rows show missing accessibility qualifiers like pub for struct fields which can cause issues.

• Other Failures:

  • Issues like no such table for profiles, drawings, and accounts indicate missing definitions in the Rust test setup.
  • Warnings about "UNSTABLE" commands suggest code that may be relying on deprecated or unsupported features.

2. Recommendations

Specific Documentation Changes:

• Update fields in Rust structs for visibility:

  • Section: Rust Struct Definitions
  • Change: Add pub visibility modifier for struct fields:

    pub struct Address {
        pub street: String,
        pub zip: i32,
    }

• Provide clear setup instructions for test database:

  • Section: Test Setup
  • Change: Include examples of how to create required tables in the setup phase.

  ctx.db.create_table("profiles");

• Clarify dependency versioning practices:

  • Section: Dependency Management
  • Change: Add guidance for locking versions to avoid issues when publishing via cargo.

  For stable builds, ensure to lock dependency versions in your `Cargo.toml`.

3. Priority

1. Table visibility in Rust structs - High impact; affects struct accessibility across tests.
2. Clear test database setup instructions - High impact; avoids common "no such table" errors.
3. Dependency management guidance - Medium impact; helps stabilize the project during publish processes.

---

C# Failures

1. Root Causes

• The majority of C# failures show no such table errors, suggesting that the test environment is not properly initializing the required tables.
• The publish_error: spacetime build failed (exit=1) indicates compilation issues with improper annotations or methods.

2. Recommendations

Specific Documentation Changes:

• Update table annotations for C# classes:

  • Section: C# Struct/Classes Definitions
  • Change: Ensure all tables have the correct attribute specifications:

  [Table(Name = "User", Public = true)]
  public partial struct User { ... }

• Clarify initialization for the test setup:

  • Section: Initialization of Test Data
  • Change: Include specific setup steps to create necessary tables before tests run:

  public static void InitializeDatabase(ReducerContext ctx) {
      ctx.Db.User.Insert(new User{ ... });
  }

• Ensure method annotations are clear:

  • Section: Reducer Methods
  • Change: Include notes on required attributes for methods to function correctly in different test setups.

  Methods defined as reducers must include specific annotations to be correctly parsed.

3. Priority

1. Update table and method annotations - High impact; fixes multiple failure points immediately.
2. Add clear initialization for database tests - High impact; prevents repeated "no such table" issues.
3. Add method annotation guidelines - Medium impact; helps clarify binding for reducer functions.

---

By addressing these documentation root causes in high-priority areas, the robustness and reliability of benchmark tests in both Rust and C# can be significantly improved, leading to more reliable development and testing practices.

[JulienLavocat]

/update-llm-benchmark

[clockwork-labs-bot]

LLM Benchmark Results (ci-quickfix)

Language	Mode	Category	Tests Passed	Task Pass %
Rust	rustdoc_json	basics	23/27	82.6% ⬇️ -0.7%
Rust	rustdoc_json	schema	29/34	80.0%
Rust	rustdoc_json	total	52/61	81.4% ⬇️ -0.4%
C#	docs	basics	12/27	61.1%
C#	docs	schema	10/34	31.5%
C#	docs	total	22/61	47.7%

Compared against master branch baseline

_{Generated at: 2026-01-20T14:40:49.725Z}

Failure Analysis (click to expand)

Benchmark Failure Analysis

Generated from: /__w/SpacetimeDB/SpacetimeDB/tools/xtask-llm-benchmark/../../docs/llms/docs-benchmark-details.json

Summary

• Total failures analyzed: 23

Analysis

Analysis of SpacetimeDB Benchmark Failures

Rust Failures

1. Root Causes

• Publish Errors: All three publishing issues stem from potential misconfigurations or missing dependencies in the provided code examples, particularly regarding the spacetimedb crate.
• Insert/CRUD Errors: Multiple failures are related to the non-existence of tables (e.g., users, results). The examples do not sufficiently explain how to initialize these tables prior to CRUD operations. This leads to back-end errors indicating that the necessary tables have not been created.

2. Recommendations

• Update Example Completion:

  • Ensure all example code snippets include table initialization steps before running any CRUD operations. Add comments explicitly guiding users to create tables first.

• Documentation Sections to Update:

  • "Getting Started" Section:
    • Add a step detailing the creation of tables, with examples of how to call an initialization reducer at the app start.
    • Example correction text:

      // Ensure this reducer is called at app start
      ctx.db.create_table::<User>();
      ctx.db.create_table::<ResultRow>();

• Additional Error Handling:

  • Expand on error handling methods for better understanding, particularly around handling NoSuchTable exceptions.

3. Priority

• High Priority: Provide a comprehensive section on "Initializing Tables" with explicit code examples, ensuring users understand the need to create their tables prior to depending on them in CRUD operations.

---

C# Failures

1. Root Causes

• Non-existent Tables for CRUD Operations: Similar to Rust, many errors arise from attempts to access tables that have not been created. The documentation fails to guide users on initializing these tables.
• Incomplete or Incorrect Example Structures: Many code examples don't adhere to conventional naming practices, leading to confusion, e.g., public partial struct Users instead of public partial struct User.

2. Recommendations

• Correct Naming and Structure Conventions:

  • Updates should follow the naming pattern consistently (e.g., either always singular or always plural for table names).

• Documentation Sections to Update:

  • "Basic CRUD Operations" Section:
    • Introduce guidelines on how to initialize required tables before performing CRUD operations.
    • Emphasize the need for an Init reducer that initializes the tables with appropriate entries, and provide a corrected example:

    // Example of an Init reducer that should be called at application start
    [SpacetimeDB.Reducer(SpacetimeDB.ReducerKind.Init)]
    public static void Init(ReducerContext ctx) {
        ctx.Db.User.Insert(new User { Id = 1, Name = "Example" }); 
        ctx.Db.Result.Insert(new Result { Id = 1, Value = new Score { Left = 0, Right = 0 } });
    }

• Error Handling Documentation:

  • Provide a clear explanation on managing NoSuchTable errors within the documentation.

3. Priority

• High Priority: Focus on expanding the "Basic CRUD Operations" section to include structured examples on initialization, using singular forms for table structures as consistent practice. This would enhance understanding and usability among developers targeting C#.

---

By addressing the outlined discordances in documentation while maintaining a clear, consistent theme, you will significantly reduce benchmark test failures for both languages, boosting user understanding and success in leveraging SpacetimeDB.

[JulienLavocat]

/update-llm-benchmark

[clockwork-labs-bot]

LLM Benchmark Results (ci-quickfix)

Language	Mode	Category	Tests Passed	Task Pass %
Rust	rustdoc_json	basics	22/27	74.3% ⬆️ +6.9%
Rust	rustdoc_json	schema	29/34	80.0% ⬇️ -10.0%
Rust	rustdoc_json	total	51/61	76.9% ⬇️ -0.8%
C#	docs	basics	12/27	61.1% ⬆️ +2.8%
C#	docs	schema	10/34	31.5%
C#	docs	total	22/61	47.7% ⬆️ +1.5%

Compared against master branch baseline

_{Generated at: 2026-01-20T22:12:30.529Z}

Failure Analysis (click to expand)

Benchmark Failure Analysis

Generated from: /__w/SpacetimeDB/SpacetimeDB/tools/xtask-llm-benchmark/../../docs/llms/docs-benchmark-details.json

Summary

• Total failures analyzed: 24

Analysis

Analysis of SpacetimeDB Benchmark Failures

Rust Failures

1. Root Causes:

   • Naming Convention: Inconsistency in struct names between expected and actual implementations (e.g., User vs. Users).
   • Primary Key and Unique Annotations: Missing or improperly formatted annotations in the structures.
   • Functions
     • Reducer naming disparities that lead to schema mismatches (e.g., add_entity() vs. expected function).
   • Table Creation Errors: Missing or wrongly specified table names lead to "no such table" errors during runtime.

2. Recommendations:

   • Documentation File: Update the “Rust API Guidelines” section.
     • Change 1: Enforce a strict naming convention for struct names and tables, ensuring they match in all uses.
       • From: "#[table(name = users)]"
       • To: "#[table(name = User)]"
     • Change 2: Add comprehensive examples of using annotations for primary keys and unique constraints.
     • Change 3: Ensure reducer naming conventions are consistent between examples and the API documentation.
     • Change 4: Highlight the requirement for tables to be defined before being referenced.

3. Priority:

   • High-impact changes should focus on the naming conventions of struct and table names, as this seems to be a recurring source of errors.

---

C# Failures

1. Root Causes:

   • Errors with Table Definitions: A significant number of failures stemmed from improperly defined or missing table names in the struct annotations.
   • Inconsistent Method Signatures: Reducer methods sometimes do not align with their expected signatures.
   • Use of Attributes: Some attributes, like Table, lack accurate definitions or are inconsistently used (e.g., missing public access modifiers).
   • Data Class Definition: Missing public access modifiers lead to problems during access in different scopes.

2. Recommendations:

   • Documentation File: Update “C# Usage Documentation”
     • Change 1: Standardize usage of public modifiers for all data classes and methods. Ensure documentation states that omitted modifiers will lead to access errors.
     • Change 2: Create a dedicated section for explaining the use of attributes, focusing on examples of Table, PrimaryKey, and uniqueness specifications.
     • Change 3: Provide a clear framework for establishing the naming conventions for methods (e.g., InsertUser should be consistent and reflect expected behavior).
     • Change 4: Enhance examples showing both the initial table declaration and usage in reducers to prevent "no such table" errors.

3. Priority:

   • Prioritize correcting the attribute usage and naming conventions as they provide the basic structure for declarations that directly affect the benchmark's success.

---

The above recommendations aim to create a consistent and clear guidance in the documentation that can preemptively address the issues seen in both the Rust and C# benchmark failures. Updates should prioritize clarity and consistency in naming and structuring code, focusing on how these influence benchmark success.

[cloutiertyler]

Quite a straightforward tutorial! I like it!