Corvus Ctj Handler Implementation

CTJ Handler Implementation

The Golden Rule

Any data that reaches a response body must be owned by the workspace.

The result factory (e.g., ListTodosResult.Ok(body, workspace)) calls CreateBuilder(workspace, body) which wraps the Source's backing memory — it does NOT deep-copy. If the backing memory is freed before serialization, the response is corrupted.

Document Lifetime

Workspace-Owned (correct for handlers)

var (builder, etag) = await store.ReadMutableAsync(sasToken, workspace, ct);
TodoList.Mutable list = builder.RootElement;
// builder is owned by workspace — lives until request ends
return ListTodosResult.Ok(body: (TodoList)list, workspace: workspace);

Caller-Owned (only for inspect-and-discard)

using var doc = await store.ReadAsync(sasToken, ct);
bool exists = doc is not null;
// Safe: nothing from doc reaches the response
return exists ? OkResult(...) : NotFoundResult(...);

NEVER use ParseValue

ParseValue() is being marked [Obsolete]. It creates a self-owned copy with no deterministic disposal. Always use ParsedJsonDocument<T>.Parse*() or JsonDocumentBuilder<T>.Parse(workspace, ...).

Store Pattern: Read vs ReadMutable

Provide two overloads on your store type:

public sealed class MyStore
{
    /// Read-only — caller owns and must dispose. For inspect-and-discard only.
    public async Task<ParsedJsonDocument<T>?> ReadAsync(
        JsonString sasToken, CancellationToken ct) { ... }

    /// Mutable — workspace owns lifetime. For any path where data reaches response.
    public async Task<(JsonDocumentBuilder<T.Mutable> Builder, ETag ETag)?> ReadMutableAsync(
        JsonString sasToken, JsonWorkspace workspace, CancellationToken ct) { ... }
}

When to use which:

Building Response Bodies

From literals/new data (Build pattern)

return CreateTodoResult.Created(
    body: TodoItem.Build((ref TodoItem.Builder b) =>
    {
        b.Create(id: Guid.NewGuid(), title: body.Title, status: "pending"u8);
    }),
    workspace: workspace);

From existing workspace-owned data (pass-through)

var (builder, _) = await store.ReadMutableAsync(sasToken, workspace, ct);
// Cast needed: Mutable → T (one hop), then T → Source (implicit)
return ListTodosResult.Ok(body: (TodoList)builder.RootElement, workspace: workspace);

The Two-Hop Cast

C# does not chain implicit conversions. Mutable → T is implicit, T → Source is implicit, but Mutable → Source requires an explicit cast to bridge the first hop:

// ❌ Won't compile — no direct Mutable → Source conversion
return OkResult(body: mutableItem, workspace);

// ✅ Cast to immutable type; implicit conversion to Source handles the rest
return OkResult(body: (TodoItem)mutableItem, workspace);

Note: The CTJ002 analyzer may incorrectly flag this cast as unnecessary (see issue #775). Suppress or ignore — the cast is required.

Emitting store-produced data the body holds past the handler (the deferred-body rule)

A response body's Source is not consumed when the handler returns — it is re-read later, during response validation/serialization (ValidateBody). So anything the body references must stay valid until then, not just until the handler exits:

• A pooled document the body projects must be handed to the workspace — single value workspace.TakeOwnership(doc); a page/list PooledDocumentList<T>.TransferOwnershipTo(workspace) — so it outlives the handler. using-disposing it at handler return is a use-after-free (ObjectDisposedException at serialization). Inspect-and-discard checks that never reach the body are the only safe using.
• A pooled/transient scalar written via a builder (e.g. an opaque continuation token emitted (JsonString.Source)tokenUtf8.Span): a builder lambda cannot capture a Span, and a stackalloc/just-disposed buffer would dangle. Carry it as a capturable ReadOnlyMemory<byte> owned by a disposable carrier (the page) that the handler using-scopes: the synchronous Ok(...)/Build(...) copies the bytes into the response document while the carrier is alive; the carrier's Dispose returns the pooled buffer afterwards. Centralise the rent+encode in a page Create(...) factory so every backend call site stays a leak-free one-liner.

A primitive value written via b.Create(prop: value) is copied into the response document during the build — safe for a transient only if the build is synchronous and the value is alive throughout it, which the disposable-carrier pattern guarantees.

Scalar-copied vs From-wrapped (the precise rule). ResultType.Ok(body, workspace) runs the body Source closure synchronously inside CreateBuilder(workspace, body).RootElement, so a using-scoped carrier is still alive when the closure runs. Within that closure two things behave differently at serialization time:

• A scalar written via b.Create(token: (JsonString.Source)page.NextPageToken.Span) is copied into the response document during CreateBuilder → the carrier's pooled buffer can be disposed right after Ok returns (read .Span inside the closure, never as a captured Span local). This is why the page can be using-scoped.
• A From(externalDoc)-wrapped sub-document (e.g. CatalogVersionSummary.From(version) over a pooled store doc) is referenced, not copied → it is re-read at post-handler serialization, so its backing must be handed over with PooledDocumentList<T>.TransferOwnershipTo(workspace). A page can do both: TransferOwnershipTo its wrapped documents and using-dispose itself to return the pooled token buffer (the token was already copied).

A carrier that owns a pooled buffer must be a sealed class : IDisposable, never a readonly record struct. A record struct is copy-by-value, so two copies share one rented byte[] and Dispose double-returns it (pool corruption). A record struct may own a PooledDocumentList (a class — idempotent dispose) and get away with it, but the moment it also owns a rented buffer, convert it to a class (mirror SourceCredentialPage/ObservedIdentityPage; WorkflowRunPage/CatalogPage were converted from record structs for exactly this).

Response projection: decision order (run this BEFORE writing a projection)

A response body is built from a stored document. Pick the mechanism in this order — most projections are over-built because the wrong rung was chosen, and that over-building is pure allocation (managed strings, per-item closures, rebuilt arrays):

1. Is the response type congruent with the stored type? (Same fields, same required set, nothing the response must hide.) If yes → whole-document From(), for the single-document response and the list:
   • Single: return GetXResult.Ok(Models.XView.From(doc.RootElement), workspace) + workspace.TakeOwnership(doc).
   • List: per item array.AddItem(Models.XView.From(item)) + page.TransferOwnershipTo(workspace).
   • The single-document and list responses MUST use the same mechanism. A field-copy list whose single-document sibling is a whole-doc From() is a missed collapse — check the single-doc site first; if it wraps with From(), the list collapses too (per item + ownership transfer). (This was the ToRuleSource/ToViewSource bug: the list field-copied while create/get/update already wrapped.)
2. Must the response hide stored fields? (e.g. a summary that drops an internal scopes/expiresAt/usageTags.) Only then field-select — and carry each selected leaf bytes-native: Models.JsonString.From(stored.RawAccessor) / Models.JsonDateTime.From(stored.RawAccessor), never (string)stored.X or the nullable XxxValue/XxxOrNull accessors (see below).
3. Build the list/object closure-free. Thread the context (Build<TContext>), don't capture in a lambda — see corvus-builder-context-threading. The list Build<TContext> is ref-scoped to its in argument, so build it inline in the handler, not in a returned helper.

The XxxOrNull / XxxValue anti-pattern (the realising ternary)

Never feed a generated builder from the nullable convenience accessors:

// ❌ XxxValue/XxxOrNull DISCARD Undefined-ness → the ternary's `default` writes a REAL value
//    (DateTimeOffset default = the EPOCH; string = null/empty), not an omitted field. Latent bug.
lastUpdatedAt: stored.UpdatedAtValue is { } v ? v : default,
description:   stored.DescriptionOrNull is { } d ? d : default,

// ✅ bare From() of the RAW accessor PROPAGATES Undefined → an absent field is OMITTED, no ternary
lastUpdatedAt: Models.JsonDateTime.From(stored.LastUpdatedAt),
description:   Models.JsonString.From(stored.Description),

The if (x.IsNotUndefined()) { local = From(x); } guard is the same smell — redundant, since From() already propagates Undefined.