Table of Contents

Orleans.Lattice.Api.Schema

A transport-agnostic schema-management control facade for Orleans.Lattice.Schema.

What is it?

Orleans.Lattice.Api.Schema is the control plane of a cluster's schema system. The Orleans.Lattice.Schema package adds enforcement, policy storage, dead-letter handling, remediation, compliance scanning, and the optional versioning engine reached through .NET service interfaces; this package adds the administrative surface an operator dashboard, a CLI, or an internal admin service needs to manage policies, inspect rejected writes, drive remediation, and audit compliance - over a single surface with no wire dependency.

It is built the same way as the read-only Orleans.Lattice.Api.State, read-write Orleans.Lattice.Api.Data, and backup Orleans.Lattice.Api.Backup facades:

  • A transport-agnostic facade. A single control surface (ILatticeSchemaControl, a public contract in the shared Orleans.Lattice.Api.Abstractions package) exposes policy, dead-letter, versioning, remediation, compliance-audit, and capability-probe operations over plain request / response records. It has no wire dependency, so the same surface serves an in-process consumer and a remote one.
  • A code-first gRPC binding (the sibling Orleans.Lattice.Api.Schema.Grpc package) that projects this facade onto a remotely callable service and typed client. This package ships no transport of its own; it is the contract every binding adapts over.

Core properties

  • Opt-in and absent by default. Nothing registers unless the host calls AddLatticeSchemaApi() on the silo, and once added the facade does no background work until a method is called.
  • Fail-closed by construction. Every operation authorizes the tree's scope through the schema engine's internal authorization component before touching the admin plane. Reads require Read authority; mutations require SchemaAdmin authority.
  • Bounded-memory dead-letter streaming. Dead-letter inspection can stream diverted schema-rejected writes without materializing the whole set in memory.
  • Versioning stays separate. Schema versioning is enabled by AddLatticeSchemaVersioning(...). A version operation on a silo without versioning registered throws a clear InvalidOperationException at call time rather than failing dependency resolution.
  • Read-only capability probe. A caller can ask, with no side effects, which schema operations it may perform over a given tree. The probe runs fail-closed Read and SchemaAdmin checks and reports the result as capability flags, so a UI can grey out actions the caller cannot perform without ever mutating state. The probe is advisory only: it never replaces the per-operation authorization each real call still performs.

Ordering

AddLatticeSchemaApi() must be called after AddLatticeSchemaEnforcement(...): the schema engine is the source of truth for the policy, dead-letter, remediation, compliance, and authorization seams this facade drives. Calling it first fails fast at registration with an actionable message.

AddLatticeSchemaVersioning(...) is separate and optional. Register it when versioning operations should be available.

Surface

The facade operations (each projected by the gRPC binding as one RPC when the sibling binding is registered):

Operation Purpose
Set policy Set a tree's write-validation policy.
Clear policy Remove a tree's policy and report whether one was present.
Get policy Read a tree's policy, or absent.
List dead letters Stream the diverted schema-rejected writes with bounded memory.
Count dead letters Count the diverted schema-rejected writes.
Set version config Set a tree's versioning config.
Get version config Read a tree's version config, or absent.
Advance target version Advance the declared target version without migrating existing values.
Advance and migrate Advance the target version and migrate existing values to it.
Migrate to target version Migrate existing values up to the current target version.
Clear version config Remove the tree's version config and report whether one was present.
Remediate Apply a value transform across a tree and adopt a target policy (deprecated: blocks until done; see Start remediation).
Get remediation status Read the status or last report of remediation for a tree.
Scan compliance Run a read-only compliance audit and return counts and reasons. Deprecated in favour of the accept-then-poll scan below.
Start a compliance scan Start the same audit in the background and poll its progress and report (ILatticeSchemaComplianceOperations; see Schema operations).
Start remediation, start migration, start advance and migrate Start the run in the background and return at once; poll the operation for its phase and values processed (ILatticeSchemaOperations; see Schema operations).
Operation status, list, cancel Read, page or cancel the caller's remediation and migration operations.
Probe capabilities Report, with no side effects, which schema operations the caller may perform over a tree.

Reference

  • API reference - the public options and model types, and the facade operations by name.
  • Schema operations - the accept-then-poll compliance scan, remediation and migration, and migrating from the deprecated blocking verbs.
  • Configuration - the public options properties, their types, and defaults.
  • Architecture - how the facade authorizes, streams dead letters, gates versioning, and audits compliance.

See also