Skip to main content

.NET changelog

Release notes for K9o.Core, from the CHANGELOG.md in the sdk-dotnet repository. Read on 17 November 2026 at 15:55 UTC.

1.5.2​

Changed​

  • K9O_TIER_FEATURE_GATED is no longer documented as an error to expect: the platform no longer gates features by plan.
  • The LLM model type no longer has MinTier, which the gateway does not send.
  • The tierGating option is removed from sign-in provider creation; the platform no longer gates features by plan.
  • README: Architecture at a glance, illustrations, and the package table lists only the packages for that SDK.

1.5.0​

Added​

  • Approvals.Comments.AddAsync(pendingId, body, visibility) and Approvals.Comments.ListAsync(pendingId, limit, cursor): comments on a pending change (POST | GET /@<project>/pending-approvals/<pendingId>/comments), returning ApprovalComment (Id, CaseId, AuthorId, Visibility, Body, CreatedAt). body is 1 to 4000 characters, visibility is everyone or approvers_only and is fixed once posted; both, pendingId and limit (1 to 200) are checked before sending (K9O_INVALID_FIELD_VALUE). The list is oldest first, limited to what the caller may see, and its next-page cursor is Envelope<T>.NextCursor (null on the last page). No edit and no delete. Posting needs a session. Gateway errors pass through as KError: K9O_APPROVAL_COMMENT_NOT_ELIGIBLE (403), K9O_APPROVAL_COMMENT_CLOSED (409), K9O_NOT_FOUND (404), K9O_RBAC_DENY (403), K9O_INVALID_FIELD_VALUE (400).

  • Realtime.ReplayAsync(topic, fromSequence, untilSequence, limit): read a realtime topic back in one call (POST /@<project>/realtime/replay), returning a RealtimeReplayPage (Events as RealtimeEvent, NextCursor, HasMore, Resync). The topic is required and checked before sending (1 to 200 characters), sequences are 0 or more, limit is 1 to 10000 and defaults to 1000 (K9O_INVALID_FIELD_VALUE). A topic with no stored history answers no events and Resync reread-source. Audit.ReplayAsync is unchanged.

  • KError.RequestId is filled from the gateway's x-k9o-request-id response header (any letter case) on every non-2xx answer, including a stream open and a non-JSON body, when the error body carries no requestId; a body value still wins, and with neither it stays null.

  • Gate.SignInAsync first asks the project which region holds the email (POST /@<project>/gate/locate, the email only, no Authorization header) and sends the password to that region's host only if it is a region host of your own organization and apex over https; otherwise it uses the base URL. The answer is not cached; a bounded in-memory hint per refresh token sends RefreshTokenAsync and SignOutAsync to the host that issued the session. If the locate step answers 404, the base URL is used. A 429 K9O_RATE_LIMITED or 503 K9O_GATE_REGION_UNAVAILABLE from that step is thrown as KError with no password sent and no retry (Gate.RateLimitedCode, Gate.RegionUnavailableCode).

  • The custody check before each EncryptAsync names the crypt (GET /crypto/mode?crypt=<crypt>), so a personal access token or workload policy scoped to named crypts can encrypt. ModeAsync() sends no query.

  • Crypto.ModeAsync(crypt): an optional crypt for the public mode read (GET /crypto/mode?crypt=<crypt>); the crypt is checked before sending (K9O_INVALID_FIELD_VALUE), and ModeAsync() is unchanged.

  • Crypto: EncryptAsync, DecryptAsync and RewrapAsync for server-side encryption with the project's platform-managed key (POST /crypto/encrypt | decrypt | rewrap), in batches of 1 to 100 items with a crypt and an optional context. The SDK encodes base64 for you and checks crypt (a registered name, [a-z0-9-]{1,64}, not actions), item count and sizes before sending (K9O_INVALID_FIELD_VALUE, K9O_PAYLOAD_TOO_LARGE). Machine calls only (service tokens, personal access tokens); IAM on the crypt decides, default floor PROJECT_EDITOR. Encrypt checks the custody mode on every call (Crypto.ModeAsync(), no cache) and sends custodyEpoch; for BYOK and HYOK it uses the client core registered with Crypto.UseClientCore(core) (ICryptoClientCore) and never sends plaintext to the platform, and without one raises K9O_ZK_CLIENT_CORE_UNAVAILABLE (501). An unknown mode or a failed check sends nothing. Decrypt and rewrap try the platform first and reroute client-side on a 409 K9O_ZK_STORE_FLOW_REQUIRED with route client. The ciphertext is covered by the project key's lifecycle only, not by per-subject erasure, and is not opened by client-side Kibo or the extension route. Never retried automatically. Not live on the gateway yet (404 today).

  • Crypto.EncryptAsync follows the route in the project's mode answer: on BYOK and HYOK only route "server" (with an epoch) sends plaintext to the server, a missing route uses the client core, and an unrecognised route is refused with K9O_CRYPTO_CUSTODY_UNKNOWN (any custody mode) with nothing sent. CryptoMode.RouteRaw carries the raw value. The mode is read before every encrypt.

  • Crypto.Crypts: ListAsync(), CreateAsync(name) and RetireAsync(name) for the project's crypt registry (GET | POST /crypto/crypts, POST /crypto/crypts/{name}/retire), returning Crypt (Name, Status active or retired, CreatedAt, RetiredAt or null). A bad name is refused before anything is sent (K9O_INVALID_FIELD_VALUE, Context["field"] is name); create sends only the name. An answer with no list, an unknown status, no name or createdAt, or a retiredAt that is neither text nor null raises K9O_INTERNAL_ERROR (crypto.crypts.<op>: the gateway answered ...). Gateway errors pass through as KError (409 K9O_CRYPT_ALREADY_EXISTS, K9O_CRYPT_LIMIT_EXCEEDED, K9O_CRYPT_RETIRED; 404 K9O_CRYPT_NOT_FOUND; K9O_ACCESS_DENIED, K9O_IAM_POLICY_DENIED, K9O_RBAC_DENY), with new constants Crypto.CryptAlreadyExistsCode and Crypto.CryptLimitExceededCode. Create and retire need crypto:manage_crypts (PROJECT_ADMIN by default); a personal access token is refused on retire. A retired or unregistered name is refused on encrypt only; decrypt and rewrap never read the registry.

  • Crypto.FederatedTokenAsync(crypt, op): a token for encrypt, decrypt or rewrap on a crypt (POST /crypto/federated-token), valid at most 15 minutes, returned as CryptoFederatedToken (Token, ExpiresAt, Issuer, Subject, Audience, Kid, and Provider and ProjectId when the gateway sends them, otherwise null). Crypt and op are checked before sending (K9O_INVALID_FIELD_VALUE); an answer missing the token or any claim raises K9O_INTERNAL_ERROR. The token is a credential: ToString() redacts it. Its Subject reads <project>:crypt:<crypt>:op:<op>. Never retried.

  • K9oOptions.ExpectedKeyRefs: the key identifiers of your own KMS or HSM keys. The router passes them to the registered ICryptoClientCore on every encrypt, decrypt and rewrap in a new CryptoCoreOptions argument (null when unset), and the core must refuse a key not in the list, version ignored, before it uses any token or makes any network call. Checked when the client is built: it must not be empty, and an entry cannot be blank, contain whitespace or * (K9O_INVALID_FIELD_VALUE, Context["field"] is expectedKeyRefs). Set it from your own cloud configuration, never from the platform. The three ICryptoClientCore methods gain an options parameter, and a core declares that it enforces the pin with EnforcesExpectedKeyRefs (default false); with the option set and no declaration the call is refused with K9O_CRYPTO_KEY_PIN_UNENFORCED before the core is called. Crypto.KeyRefMatches(keyRef, expected, provider) compares by the rule of the KeyRefProvider you pass (Aws, Gcp, Azure or Vault; required, never guessed from the reference) (AWS whole reference; GCP without the version; Azure the first five parts in lower case; Vault <path>/<key> without :<version>); KeyRefProvider is exported.

  • Keys.RotateAsync(keyId, options) takes a step-up hook (KeyRotateOptions.StepUp): on 401 K9O_STEP_UP_REQUIRED the hook receives the challenge plus the HTTP method and URL and returns the proof; the SDK retries once with x-k9o-step-up-proof. KError.StepUp carries the challenge when there is no hook.

  • Rampart: ClassifyAsync(input, label) refuses a non-object input before sending (K9O_INVALID_FIELD_VALUE), returns the verdict and the signed receipt as received, JwksAsync() reads the public key feed, and VerifyReceiptAsync(result or receipt, input, options) checks a receipt locally and returns the verdict from its signed claims. The expected issuer is the one the key feed advertises (JwkSet.Issuer; the Issuer option overrides it), and the expected project is the ProjectId on the classify result (the ProjectId option overrides it). A failure throws ReceiptRefusedException with a Reason from a closed set (KeyUnknown, Alg, Typ, Issuer, Project, ProjectUnknown, Expired, NotYetValid, InputHash, Signature, Malformed). Keys are fetched once and kept for the client's life, with one refetch on an unknown kid. Rampart is advisory: it blocks nothing, and an unavailable classifier throws. A long input is scored in overlapping windows and the highest injection score decides; past 16 windows (about 6,000 tokens) the answer is 413 K9O_RAMPART_INPUT_TOO_LONG with no verdict, and 503 K9O_RAMPART_CLASSIFIER_UNAVAILABLE still means the classifier could not answer. The thresholds (calibration rampart-launch-v1) are a starting calibration and may move; a change is a new CalibrationVersion.

  • Analytics, Analytics.Rollups, Analytics.Schedules and Rollups: datasets (ListAsync, GetAsync, CreateAsync, DeleteAsync, QueryAsync with SQL, ReadAsync with a cursor, WriteAsync and WriteNdjsonAsync, UploadAsync for CSV and JSON files with an optional manifest, DownloadOriginalAsync, MaterializeAsync), their rollups and schedules (CreateAsync, ListAsync, DeleteAsync, ReattestAsync), and the project's rollups (Rollups.ListAsync, ReadAsync, and SubscribeAsync for closed cells over the reconnecting change feed: RollupCellEvent reads the cell frame's payload (CellKey, Bucket, Dims, Final, Measures, and Status/Reason for a suppressed cell), resumes by the stream id and dedupes on EventId; a reread-source resync reaches OnResync). ReattestAsync is human only: a service, workload or extension token gets 403 K9O_RBAC_DENY (reason: human_only). A rollup or schedule pauses when it is not re-attested within its ReattestIntervalDays (7, 30, 90 or 365).

  • Keys: ListAsync(status), GetAsync(keyId) and RotateAsync(keyId) for the project's encryption keys (Id, Version, Status, CustodyMode, CreatedAt, RotatedAt, ByokRef, HyokRef; no key material). Rotation needs the project admin role and a fresh step-up proof (401 K9O_STEP_UP_REQUIRED without one; ListAsync is not paged and exposes no cursor), answers 409 K9O_STATE_CONFLICT while one is running and 429 K9O_RATE_LIMITED past 3 in 24 hours, and is never retried.

  • Audit.TailAsync(options): follow the project audit log live (AuditEventId, Type, ActorType, OccurredAt, Outcome, EventId; the five fields are read from the frame's payload, events are deduplicated on the frame's eventId and the stream resumes with its id). Audit.ReplayAsync returns a typed AuditReplayPage (Events with Sequence, NextCursor, HasMore) and the tail pages through it while HasMore with Last-Event-ID resume, dedupe, heartbeat and idle reconnect. On a replay-ledger resync the tail catches up by itself (Audit.ReplayAsync after the last delivered AuditEventId, skipped when none yet), yields the missed events once and continues live; OnResync is an optional informational hook and ReplayOnResync = false turns the automatic replay off. warden.checkpoint events are in the log and the replay, not in the live tail. After a resync the tail now reconnects first, then replays, then merges (nothing lost, each event once); a new connection starts at the live head and may re-send the last few seconds of events, each yielded once (the informational resync that opens it is ignored; use ReplayAsync for history); ReplayAsync returns at most 1000 events per call unless limit (up to 10000) is given.

  • VerifiedClassification.Windows: the number of windows scored, read from the signed windows claim (1 when the input fits one window or the receipt has no such claim). VerifyReceiptAsync ignores claims it does not know.

  • KError.RetryAfterSec also reads the Retry-After header when the error body gives none. Meta.Schema carries a dataset's columns on the first page of Analytics.ReadAsync.

  • Jcs.Canonicalize and Jcs.Sha256Hex (the platform's JSON profile: keys in UTF-8 byte order, integers only up to 2^53-1) and Ed25519.Verify (RFC 8032, built on System.Numerics.BigInteger; .NET has no built-in Ed25519). No new package dependencies.

  • Moat: a local guard for model calls with no network access. Messages(untrusted) pins your prompt as the only system message and refuses role and system markers, CheckOutput(text) enforces an output schema and an optional PII filter, PromptSha256() hashes the prompt. Input and output schemas use a small JSON Schema subset; anything else throws MoatSchemaException. Refusals are MoatResult<T> values with a MoatReason (RoleMarker, InputSchema, OutputSchema, Pii).

  • Moat marker matching follows the shared normalisation rule: NFKC, combining marks ignored, default-ignorable characters removed (fixed range table), a small set of Cyrillic and Greek look-alikes of the marker letters read as the Latin letter (not general homoglyph detection), case-folded, horizontal whitespace collapsed, matched line by line; the text sent to the model is unchanged. The constructor throws MoatConfigException when the runtime cannot do NFKC (InvariantGlobalization).

  • Custody.StatusAsync(): read-only custody status of the project (Mode, Attached, Provider, LastJob, Hsm). Needs the project admin or auditor role.

  • VectorSearch on the select builder sends the embedding in the request body, so real embeddings work. It cannot be combined with TextSearch.

  • KError.RetryAfterSec: the retryAfterSec number from the object when it is finite and 0 or more, else null. It is a field only; retry timing is unchanged. The KError constructor takes it as an optional last argument.

  • RequireApproval() on single-record writes: From(c).Insert(record), Update(patch).Eq("id", ...) and Delete().Eq("id", ...) queue the write for approval (HTTP 202) instead of applying it. ExecuteAsync<T>() then answers a GatedWrite<T>: IsQueued with a QueuedChange in Queued, or, when an auto_approve policy applies the write at once, the row in Applied. Upserts and bulk writes do not take it. Insert(record) is new; InsertAsync is unchanged. Meta.Approval carries the queued status.

  • Functions.Triggers: ListAsync, CreateAsync, UpdateAsync and DeleteAsync for a function's event triggers (Collection, Events, Filter, Enabled, LogOkInvocations). DeleteAsync answers 204, so Data is null. The SDK checks Events (1 to 4 of insert, update, delete, upsert) and the collection name before sending.

  • Schedules: ListAsync, GetAsync, CreateAsync, UpdateAsync, DeleteAsync, RunsAsync and RunNowAsync for scheduled triggers. ListAsync takes status, functionName, limit and cursor. A schedule interval under 5 minutes is rejected with 400 K9O_INVALID_FIELD_VALUE (field schedule_expression), on every plan.

  • EndUsers: ListAsync and GetAsync for the project's end users, and EndUsers.RoleGrants.ListAsync, GrantAsync and RevokeAsync for the roles they hold. RevokeAsync of an unknown id answers Revoked false, not an error.

  • Vectors: NearestAsync searches a vector collection with the embedding in the request body (any common size, up to 16000 numbers), and UpsertAsync stores 1 to 1000 rows. Collection names start with _.

  • Approvals.ListAsync(status, limit, cursor) pages the queue: Meta.Cursor.Next is the next page's cursor, null on the last page. The existing ListAsync(status, limit) calls are unchanged.

  • BulkApprovalsResult.Failed: the rows a bulk call matched but could not decide (Id, Code, Reason), empty when none failed. The call answers 200 even when rows fail, so compare AffectedIds with what you intended.

  • Realtime.SubscribeAsync keeps its feed alive: it reconnects with Last-Event-ID after a stream ends (the gateway closes each after at most 300 seconds) or the connection drops, waits the server's retry: delay (default 1 second, capped exponential backoff to 30 seconds), drops duplicates by EventId (last 1024 kept), and reconnects when nothing arrives for 45 seconds. A 4xx answer is thrown once as a KError; 5xx and network errors are retried.

  • RealtimeEvent.EventId, and RealtimeSubscribeOptions.OnResync (an optional fourth argument to SubscribeAsync): on an event: resync frame the callback receives a ResyncInfo (Reason, Action) and the feed continues on a fresh connection without Last-Event-ID. A resync frame is never yielded as an event.

  • Metadata: Index.DeclareAsync and Index.GetAsync declare the columns of a collection that can be filtered, searched and followed; SetAsync writes declared columns of one record; FilterAsync, SearchAsync and Vectors.NearestAsync read them; SubscribeAsync follows changes live. Column names are sent as metadata.<name> and the prefix is added when missing. The SDK checks the surface, limits, metric, embedding, cursor rule and 64-column limit before sending. storage: surfaces are passed through (the gateway answers 501 K9O_NOT_IMPLEMENTED); NearestAsync returns no score and at most 50 rows; SearchAsync has no second page; change events carry the collection and record id only. SubscribeAsync uses the same reconnecting reader as Realtime.SubscribeAsync (Last-Event-ID, dedupe, OnResync); FromSequence applies to the first connection only.

  • README: what an event-trigger function receives (the JSON payload, redaction, triggeredAt, and deduping on eventId).

Fixed​

  • Realtime.SubscribeAsync, Metadata.SubscribeAsync and Rollups.SubscribeAsync no longer reconnect forever without delivering anything. On a new connection (no Last-Event-ID and no FromSequence) the gateway opens with an informational event: resync and then sends events on the same stream; the feed treated that opening resync as a lost position, closed the connection and called OnResync each time. It is now ignored, and OnResync is called only for a resync that arrives after an event or on a connection that resumed with Last-Event-ID or started from a FromSequence.
  • An error body whose recommendation is an object, such as {"action": "..."} or {"retryAfterSec": 30, "note": "..."}, no longer loses the text. KError.Recommendation is the object's action, else its note, else null; any other JSON type gives null, and the error is always decoded. This covers normal responses and stream-open errors.
  • Storage.From(b).UploadAsync sent unquoted multipart field names and an extra filename*= parameter, which the gateway answered with 500. Fields are now name="file"; filename="x.txt", and metadata is sent only when supplied.
  • Streams.SubscribeAsync ignored its CancellationToken while the connection was quiet; cancelling now ends the enumeration at once.
  • JSON request bodies are sent with a Content-Length. They used to go out chunked, and the gateway refuses a large chunked body with a 411 (a big Rampart input, a large crypto batch).

1.4.0 — 2026-10-26​

Added​

  • Ai.GenerateAsync: run a prompt through an LLM, with an optional Model. Same result as Compute.Llms.InvokeAsync.
  • Streams: CreateAsync, ListAsync, GetAsync, DeleteAsync, PublishAsync, ReplayAsync and SubscribeAsync for user data streams. SubscribeAsync reconnects from the last sequence.
  • QueryAsync(sql, params): run one read-only SQL statement. params is a list (positional) or a dictionary (named :name placeholders, rewritten to $n).
  • SearchAsync(collection, options): full-text search over a text column, best matches first, with Limit and Cursor.
  • From(c).Select().TextSearch and VectorSearch: full-text and nearest-neighbour search on the select builder.
  • Approvals: ListAsync, GetAsync, ApproveAsync, RejectAsync and BulkAsync for the pending-change queue. ApproveAsync can answer with Status still pending_approval; ListAsync is not paginated; BulkAsync skips failed rows silently, so compare AffectedIds with what you intended.
  • ApprovalPolicies: ListAsync, CreateAsync and DeleteAsync for the rules that decide which writes are queued.
  • Schema.Collections.ListAsync(limit, cursor): list the project's collections by name, with Meta.Cursor.Next for the next page.

Changed​

  • README description.
  • Function deploy examples use the sandbox tier.

1.3.0 — 2026-10-26​

Every method now matches the gateway and is checked by a contract test.

Changed​

  • Projects.CreateAsync takes CreateProjectInput with DisplayName (required) and optional Slug, Region, CustodyMode. GetAsync and UpdateAsync use the projects routes.
  • Functions.DeployAsync takes Name, Runtime, Tier (gateway or sandbox), ArtifactKey, Version and Description. Inline code is gone.
  • Functions.InvokeAsync sends {payload} and accepts InvokeOptions. Functions.ListAsync accepts limit and cursor.
  • Policies CreateAsync, UpdateAsync and ValidateAsync take a PolicyInput document. Policies.ListAsync takes only status.
  • Audit.QueryAsync filters are EventType, ActorId, After, Before, Limit, Cursor.
  • Role grants use /role-grants and identity providers use /identity-providers, with a typed CreateIdpInput.
  • Org.DefaultLlm returns an object. Org.Smtp.SetAsync takes PasswordRef and FromAddress; TestAsync takes to and subject.
  • Me.ApiTokens.CreateAsync takes label, scopeManifest and ttlSeconds. Me.Sessions.RevokeAsync and RevokeAllAsync use the session routes.
  • Compute.Llms.InvokeAsync parameters are flat and the result has Content and Usage. Stream chunks are OpenAI-style.
  • RealtimeEvent is {Topic, EventType, Payload, OccurredAt}. Studio.Workflows.TriggerAsync sends {triggerContext}.
  • Optional fields left null are not sent.
  • The API host is read from the base URL: any <org>.api.<apex> host works and no domain is built in.

Removed​

  • Gate.VerifySessionAsync, Gate.HostedAsync, Realtime.ReplayAsync and Realtime.SubscribePollAsync.
  • Me.Notifications, Me.AuditLog, Me.DataExport.
  • Org.Groups.CreateAsync, Org.Groups.DeleteAsync, Org.Members.GetAsync, Org.Smtp.GetAsync.
  • The modality filter of Compute.Llms.ListAsync and the triggerType filter of Studio.Workflows.ListAsync.

Added​

  • Functions.UploadArtifactAsync(bytes, "wasm" | "tar") returns the ArtifactKey for DeployAsync.

1.2.0 — 2026-10-25​

  • The README now introduces the Kilimanjaro building blocks (Keep, Pulse, Gate, Kibo). No change to the public API.

1.1.1 — 2026-10-25​

  • Documentation links corrected: the documentation hub is https://docs.kilimanjaro.dev, with the website, platform API and console listed in a Links section. Package metadata points at the same places.

1.1.0 — 2026-10-25​

  • Documentation rewritten with runnable examples and expected output; internal cross-references removed from the published sources. No change to the public API.
  • Fixed: boolean filter values are sent as true / false. Eq("done", false) previously sent False.
  • Error text for update() / delete() without an id filter no longer mentions a version or a roadmap.

1.0.0 — 2026-10-23​

First public release. See the README for the full API overview.