.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_GATEDis 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
tierGatingoption 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)andApprovals.Comments.ListAsync(pendingId, limit, cursor): comments on a pending change (POST | GET /@<project>/pending-approvals/<pendingId>/comments), returningApprovalComment(Id,CaseId,AuthorId,Visibility,Body,CreatedAt).bodyis 1 to 4000 characters,visibilityiseveryoneorapprovers_onlyand is fixed once posted; both,pendingIdandlimit(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 isEnvelope<T>.NextCursor(null on the last page). No edit and no delete. Posting needs a session. Gateway errors pass through asKError: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 aRealtimeReplayPage(EventsasRealtimeEvent,NextCursor,HasMore,Resync). The topic is required and checked before sending (1 to 200 characters), sequences are 0 or more,limitis 1 to 10000 and defaults to 1000 (K9O_INVALID_FIELD_VALUE). A topic with no stored history answers no events andResyncreread-source.Audit.ReplayAsyncis unchanged. -
KError.RequestIdis filled from the gateway'sx-k9o-request-idresponse header (any letter case) on every non-2xx answer, including a stream open and a non-JSON body, when the error body carries norequestId; a body value still wins, and with neither it stays null. -
Gate.SignInAsyncfirst 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 sendsRefreshTokenAsyncandSignOutAsyncto the host that issued the session. If the locate step answers 404, the base URL is used. A 429K9O_RATE_LIMITEDor 503K9O_GATE_REGION_UNAVAILABLEfrom that step is thrown asKErrorwith no password sent and no retry (Gate.RateLimitedCode,Gate.RegionUnavailableCode). -
The custody check before each
EncryptAsyncnames 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), andModeAsync()is unchanged. -
Crypto:EncryptAsync,DecryptAsyncandRewrapAsyncfor 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}, notactions), 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 sendscustodyEpoch; for BYOK and HYOK it uses the client core registered withCrypto.UseClientCore(core)(ICryptoClientCore) and never sends plaintext to the platform, and without one raisesK9O_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 409K9O_ZK_STORE_FLOW_REQUIREDwith 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.EncryptAsyncfollows theroutein 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 withK9O_CRYPTO_CUSTODY_UNKNOWN(any custody mode) with nothing sent.CryptoMode.RouteRawcarries the raw value. The mode is read before every encrypt. -
Crypto.Crypts:ListAsync(),CreateAsync(name)andRetireAsync(name)for the project's crypt registry (GET | POST /crypto/crypts,POST /crypto/crypts/{name}/retire), returningCrypt(Name,Statusactiveorretired,CreatedAt,RetiredAtor null). A bad name is refused before anything is sent (K9O_INVALID_FIELD_VALUE,Context["field"]isname); create sends only the name. An answer with no list, an unknown status, no name orcreatedAt, or aretiredAtthat is neither text nor null raisesK9O_INTERNAL_ERROR(crypto.crypts.<op>: the gateway answered ...). Gateway errors pass through asKError(409K9O_CRYPT_ALREADY_EXISTS,K9O_CRYPT_LIMIT_EXCEEDED,K9O_CRYPT_RETIRED; 404K9O_CRYPT_NOT_FOUND;K9O_ACCESS_DENIED,K9O_IAM_POLICY_DENIED,K9O_RBAC_DENY), with new constantsCrypto.CryptAlreadyExistsCodeandCrypto.CryptLimitExceededCode. Create and retire needcrypto: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 forencrypt,decryptorrewrapon a crypt (POST /crypto/federated-token), valid at most 15 minutes, returned asCryptoFederatedToken(Token,ExpiresAt,Issuer,Subject,Audience,Kid, andProviderandProjectIdwhen 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 raisesK9O_INTERNAL_ERROR. The token is a credential:ToString()redacts it. ItsSubjectreads<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 registeredICryptoClientCoreon every encrypt, decrypt and rewrap in a newCryptoCoreOptionsargument (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"]isexpectedKeyRefs). Set it from your own cloud configuration, never from the platform. The threeICryptoClientCoremethods gain anoptionsparameter, and a core declares that it enforces the pin withEnforcesExpectedKeyRefs(default false); with the option set and no declaration the call is refused withK9O_CRYPTO_KEY_PIN_UNENFORCEDbefore the core is called.Crypto.KeyRefMatches(keyRef, expected, provider)compares by the rule of theKeyRefProvideryou pass (Aws,Gcp,AzureorVault; 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>);KeyRefProvideris exported. -
Keys.RotateAsync(keyId, options)takes a step-up hook (KeyRotateOptions.StepUp): on 401K9O_STEP_UP_REQUIREDthe hook receives the challenge plus the HTTP method and URL and returns the proof; the SDK retries once withx-k9o-step-up-proof.KError.StepUpcarries the challenge when there is no hook. -
Rampart:ClassifyAsync(input, label)refuses a non-objectinputbefore sending (K9O_INVALID_FIELD_VALUE), returns the verdict and the signed receipt as received,JwksAsync()reads the public key feed, andVerifyReceiptAsync(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; theIssueroption overrides it), and the expected project is theProjectIdon the classify result (theProjectIdoption overrides it). A failure throwsReceiptRefusedExceptionwith aReasonfrom 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 unknownkid. 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 413K9O_RAMPART_INPUT_TOO_LONGwith no verdict, and 503K9O_RAMPART_CLASSIFIER_UNAVAILABLEstill means the classifier could not answer. The thresholds (calibrationrampart-launch-v1) are a starting calibration and may move; a change is a newCalibrationVersion. -
Analytics,Analytics.Rollups,Analytics.SchedulesandRollups: datasets (ListAsync,GetAsync,CreateAsync,DeleteAsync,QueryAsyncwith SQL,ReadAsyncwith a cursor,WriteAsyncandWriteNdjsonAsync,UploadAsyncfor 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, andSubscribeAsyncfor closed cells over the reconnecting change feed:RollupCellEventreads thecellframe's payload (CellKey,Bucket,Dims,Final,Measures, andStatus/Reasonfor a suppressed cell), resumes by the streamidand dedupes onEventId; areread-sourceresync reachesOnResync).ReattestAsyncis human only: a service, workload or extension token gets 403K9O_RBAC_DENY(reason: human_only). A rollup or schedule pauses when it is not re-attested within itsReattestIntervalDays(7, 30, 90 or 365). -
Keys:ListAsync(status),GetAsync(keyId)andRotateAsync(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 (401K9O_STEP_UP_REQUIREDwithout one;ListAsyncis not paged and exposes no cursor), answers 409K9O_STATE_CONFLICTwhile one is running and 429K9O_RATE_LIMITEDpast 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'seventIdand the stream resumes with itsid).Audit.ReplayAsyncreturns a typedAuditReplayPage(EventswithSequence,NextCursor,HasMore) and the tail pages through it whileHasMorewithLast-Event-IDresume, dedupe, heartbeat and idle reconnect. On areplay-ledgerresync the tail catches up by itself (Audit.ReplayAsyncafter the last deliveredAuditEventId, skipped when none yet), yields the missed events once and continues live;OnResyncis an optional informational hook andReplayOnResync = falseturns the automatic replay off.warden.checkpointevents 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 informationalresyncthat opens it is ignored; useReplayAsyncfor history);ReplayAsyncreturns at most 1000 events per call unlesslimit(up to 10000) is given. -
VerifiedClassification.Windows: the number of windows scored, read from the signedwindowsclaim (1 when the input fits one window or the receipt has no such claim).VerifyReceiptAsyncignores claims it does not know. -
KError.RetryAfterSecalso reads theRetry-Afterheader when the error body gives none.Meta.Schemacarries a dataset's columns on the first page ofAnalytics.ReadAsync. -
Jcs.CanonicalizeandJcs.Sha256Hex(the platform's JSON profile: keys in UTF-8 byte order, integers only up to 2^53-1) andEd25519.Verify(RFC 8032, built onSystem.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 throwsMoatSchemaException. Refusals areMoatResult<T>values with aMoatReason(RoleMarker,InputSchema,OutputSchema,Pii). -
Moatmarker 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 throwsMoatConfigExceptionwhen 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. -
VectorSearchon the select builder sends the embedding in the request body, so real embeddings work. It cannot be combined withTextSearch. -
KError.RetryAfterSec: theretryAfterSecnumber from the object when it is finite and 0 or more, elsenull. It is a field only; retry timing is unchanged. TheKErrorconstructor takes it as an optional last argument. -
RequireApproval()on single-record writes:From(c).Insert(record),Update(patch).Eq("id", ...)andDelete().Eq("id", ...)queue the write for approval (HTTP 202) instead of applying it.ExecuteAsync<T>()then answers aGatedWrite<T>:IsQueuedwith aQueuedChangeinQueued, or, when anauto_approvepolicy applies the write at once, the row inApplied. Upserts and bulk writes do not take it.Insert(record)is new;InsertAsyncis unchanged.Meta.Approvalcarries the queued status. -
Functions.Triggers:ListAsync,CreateAsync,UpdateAsyncandDeleteAsyncfor a function's event triggers (Collection,Events,Filter,Enabled,LogOkInvocations).DeleteAsyncanswers 204, soDatais null. The SDK checksEvents(1 to 4 ofinsert,update,delete,upsert) and the collection name before sending. -
Schedules:ListAsync,GetAsync,CreateAsync,UpdateAsync,DeleteAsync,RunsAsyncandRunNowAsyncfor scheduled triggers.ListAsynctakesstatus,functionName,limitandcursor. A schedule interval under 5 minutes is rejected with 400K9O_INVALID_FIELD_VALUE(fieldschedule_expression), on every plan. -
EndUsers:ListAsyncandGetAsyncfor the project's end users, andEndUsers.RoleGrants.ListAsync,GrantAsyncandRevokeAsyncfor the roles they hold.RevokeAsyncof an unknown id answersRevokedfalse, not an error. -
Vectors:NearestAsyncsearches a vector collection with the embedding in the request body (any common size, up to 16000 numbers), andUpsertAsyncstores 1 to 1000 rows. Collection names start with_. -
Approvals.ListAsync(status, limit, cursor)pages the queue:Meta.Cursor.Nextis the next page's cursor, null on the last page. The existingListAsync(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 compareAffectedIdswith what you intended. -
Realtime.SubscribeAsynckeeps its feed alive: it reconnects withLast-Event-IDafter a stream ends (the gateway closes each after at most 300 seconds) or the connection drops, waits the server'sretry:delay (default 1 second, capped exponential backoff to 30 seconds), drops duplicates byEventId(last 1024 kept), and reconnects when nothing arrives for 45 seconds. A 4xx answer is thrown once as aKError; 5xx and network errors are retried. -
RealtimeEvent.EventId, andRealtimeSubscribeOptions.OnResync(an optional fourth argument toSubscribeAsync): on anevent: resyncframe the callback receives aResyncInfo(Reason,Action) and the feed continues on a fresh connection withoutLast-Event-ID. A resync frame is never yielded as an event. -
Metadata:Index.DeclareAsyncandIndex.GetAsyncdeclare the columns of a collection that can be filtered, searched and followed;SetAsyncwrites declared columns of one record;FilterAsync,SearchAsyncandVectors.NearestAsyncread them;SubscribeAsyncfollows changes live. Column names are sent asmetadata.<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 501K9O_NOT_IMPLEMENTED);NearestAsyncreturns no score and at most 50 rows;SearchAsynchas no second page; change events carry the collection and record id only.SubscribeAsyncuses the same reconnecting reader asRealtime.SubscribeAsync(Last-Event-ID, dedupe,OnResync);FromSequenceapplies to the first connection only. -
README: what an event-trigger function receives (the JSON payload, redaction,
triggeredAt, and deduping oneventId).
Fixed
Realtime.SubscribeAsync,Metadata.SubscribeAsyncandRollups.SubscribeAsyncno longer reconnect forever without delivering anything. On a new connection (noLast-Event-IDand noFromSequence) the gateway opens with an informationalevent: resyncand then sends events on the same stream; the feed treated that opening resync as a lost position, closed the connection and calledOnResynceach time. It is now ignored, andOnResyncis called only for a resync that arrives after an event or on a connection that resumed withLast-Event-IDor started from aFromSequence.- An error body whose
recommendationis an object, such as{"action": "..."}or{"retryAfterSec": 30, "note": "..."}, no longer loses the text.KError.Recommendationis the object'saction, else itsnote, elsenull; any other JSON type givesnull, and the error is always decoded. This covers normal responses and stream-open errors. Storage.From(b).UploadAsyncsent unquoted multipart field names and an extrafilename*=parameter, which the gateway answered with 500. Fields are nowname="file"; filename="x.txt", andmetadatais sent only when supplied.Streams.SubscribeAsyncignored itsCancellationTokenwhile 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 largecryptobatch).
1.4.0 — 2026-10-26
Added
Ai.GenerateAsync: run a prompt through an LLM, with an optionalModel. Same result asCompute.Llms.InvokeAsync.Streams:CreateAsync,ListAsync,GetAsync,DeleteAsync,PublishAsync,ReplayAsyncandSubscribeAsyncfor user data streams.SubscribeAsyncreconnects from the last sequence.QueryAsync(sql, params): run one read-only SQL statement.paramsis a list (positional) or a dictionary (named:nameplaceholders, rewritten to$n).SearchAsync(collection, options): full-text search over a text column, best matches first, withLimitandCursor.From(c).Select().TextSearchandVectorSearch: full-text and nearest-neighbour search on the select builder.Approvals:ListAsync,GetAsync,ApproveAsync,RejectAsyncandBulkAsyncfor the pending-change queue.ApproveAsynccan answer withStatusstillpending_approval;ListAsyncis not paginated;BulkAsyncskips failed rows silently, so compareAffectedIdswith what you intended.ApprovalPolicies:ListAsync,CreateAsyncandDeleteAsyncfor the rules that decide which writes are queued.Schema.Collections.ListAsync(limit, cursor): list the project's collections by name, withMeta.Cursor.Nextfor 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.CreateAsynctakesCreateProjectInputwithDisplayName(required) and optionalSlug,Region,CustodyMode.GetAsyncandUpdateAsyncuse the projects routes.Functions.DeployAsynctakesName,Runtime,Tier(gatewayorsandbox),ArtifactKey,VersionandDescription. Inline code is gone.Functions.InvokeAsyncsends{payload}and acceptsInvokeOptions.Functions.ListAsyncacceptslimitandcursor.- Policies
CreateAsync,UpdateAsyncandValidateAsynctake aPolicyInputdocument.Policies.ListAsynctakes onlystatus. Audit.QueryAsyncfilters areEventType,ActorId,After,Before,Limit,Cursor.- Role grants use
/role-grantsand identity providers use/identity-providers, with a typedCreateIdpInput. Org.DefaultLlmreturns an object.Org.Smtp.SetAsynctakesPasswordRefandFromAddress;TestAsynctakestoandsubject.Me.ApiTokens.CreateAsynctakeslabel,scopeManifestandttlSeconds.Me.Sessions.RevokeAsyncandRevokeAllAsyncuse the session routes.Compute.Llms.InvokeAsyncparameters are flat and the result hasContentandUsage. Stream chunks are OpenAI-style.RealtimeEventis{Topic, EventType, Payload, OccurredAt}.Studio.Workflows.TriggerAsyncsends{triggerContext}.- Optional fields left
nullare 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.ReplayAsyncandRealtime.SubscribePollAsync.Me.Notifications,Me.AuditLog,Me.DataExport.Org.Groups.CreateAsync,Org.Groups.DeleteAsync,Org.Members.GetAsync,Org.Smtp.GetAsync.- The
modalityfilter ofCompute.Llms.ListAsyncand thetriggerTypefilter ofStudio.Workflows.ListAsync.
Added
Functions.UploadArtifactAsync(bytes, "wasm" | "tar")returns theArtifactKeyforDeployAsync.
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 sentFalse. - Error text for
update()/delete()without anidfilter 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.