Rust changelog
Release notes for k9o, from the CHANGELOG.md in the sdk-rust 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
min_tier, which the gateway does not send. A model list now deserializes without it. - 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():add(pending_id, AddApprovalCommentInput { body, visibility })(POST /@<slug>/pending-approvals/<id>/comments) andlist(pending_id, ListApprovalCommentsOptions { limit, cursor })(GETon the same path, oldest first,ApprovalCommentPage { comments, next_cursor }), both returningApprovalComment(id,case_id,author_id,visibility,body,created_at).bodyis 1 to 4000 characters andvisibilityiseveryoneorapprovers_only; a bad value is refused withK9O_INVALID_FIELD_VALUEbefore sending. Commenting needs a session. 403K9O_APPROVAL_COMMENT_NOT_ELIGIBLEand 409K9O_APPROVAL_COMMENT_CLOSEDcome back as theKError.realtime().replay(topic, ReplayOptions):POST /@<slug>/realtime/replayfor any realtime topic.topicis required;from_sequence,until_sequence,limit(1 to 10000) andafter_audit_event_idare optional. It returns aRealtimeReplay(eventsasRealtimeEvent,next_cursor,has_more,resync).RealtimeEventfields other thanpayloadnow default when a frame omits them.audit().replayis unchanged.
Fixed
realtime().subscribe,metadata().subscribeandrollups().subscribeno longer reconnect in a loop without delivering anything. The gateway opens a connection that sent noLast-Event-IDwith an informationalresyncframe (the live head), then streams events on the same connection. That openingresyncis now ignored: the stream continues,on_resyncis not called and there is no reconnect. Aresyncafter an event was delivered, or on a connection that sent aLast-Event-IDor afromSequencestart position, is still a lost position and callson_resyncas before.
Changed
- Audit tail and
audit().replaydecode the gateway's real frames. The five fields are read from the frame'spayload(not from the top of the data object), duplicates are dropped by the frame'seventIdand byauditEventId, and a reconnect resumes with the frame's SSEid(which is not the audit event id).AuditTailEventgainsevent_idandsequence;outcomeisOption<String>(the gateway sends null).AuditReplayis a page:events,next_cursor,has_more. Areplay-ledgerresync follows the replay pages whilehas_more; it now reconnects fresh first and replays while that connection's frames are buffered, so the catch-up is gapless and each event is delivered once, a new connection starts at the live head and may re-send the last few seconds (the informational headresyncon a fresh connection is ignored), andaudit().replaysendslimit: 1000unless you pass one (1 to 10000). rollups().subscribeyieldsRollupCell(event_id,cell_key,bucket,dims,is_final,measures, andstatus/reasonwithis_suppressed()for a cohort-suppressed cell) read from the frame'spayload; resume uses the frame's SSEid, repeats are dropped byeventId, and thereread-sourceresync reacheson_resync.keys().rotate(key_id, RotateOptions): astep_uphook receives the challenge (StepUpChallenge) and the request's method and URL and returns aStepUpProof { method, proof }; the SDK retries once with thex-k9o-step-up-proofheader. Without a hook the 401K9O_STEP_UP_REQUIREDcarries the challenge (StepUpChallenge::from_error).KeyList.next_cursoris removed:keys().listis not paged.rampart().classifyrefuses a non-objectinputbefore sending (K9O_INVALID_FIELD_VALUE).
Added
KError.request_idis now filled from the gateway'sx-k9o-request-idresponse header on every non-2xx answer (requests, downloads and stream opens), when the error body carries norequestIdof its own; a body value still wins. Log it and give it to support.k9o-kibo-core(thekibo-coredirectory): a separate crate withKiboCore, a readyAppCoreover the Kibo core. It builds on the core's Rust crate,kibo-kms-rest-ffi0.4.5 (Kibo core 2.16.5) or later. It converts the SDK's structs to the core's and gives the core's errors as"<CODE>: <message>". It is a separate crate so a normal build ofk9odoes not resolve or compile the core.gate().sign_infirst asks the project which region holds the email (POST /@<slug>/gate/locate, the email only, no credential), then sends the password to the region host it names, but only if that host ishttps(orhttpon a loopback base and a loopback host), has no userinfo, port, path, query or fragment, and is your own organization, gateway family and apex with the region code added or swapped in (the code must equal the answer'sregion); otherwise the base URL is used. The answer is not cached;refresh_tokenandsign_outuse the host that issued the session (a bounded in-memory hint, removed on sign-out). A 429K9O_RATE_LIMITEDor 503K9O_GATE_REGION_UNAVAILABLEfrom that step is returned as theKError, the password is not sent, and nothing is retried; a 2xx with a malformed body uses the base. Sign-in now makes two requests. If the project's locate step answers 404, the client uses the base address.KiboClientCorematches the configured key against the call'sexpected_key_refsbefore it fetches a federated token or exchanges a credential; a key outside the call's pin getsK9O_CRYPTO_UNEXPECTED_KEYon every item, with no token fetch and no seal or open.- The custody check before each
encryptnames the crypt (GET /crypto/mode?crypt=<crypt>), so a personal access token or workload policy scoped to named crypts can encrypt;crypto().mode()still sends no query. crypto().mode_for(crypt)asks the custody mode about one crypt (?crypt=<crypt>); a bad crypt is refused withK9O_INVALID_FIELD_VALUEbefore sending.crypto().mode()is unchanged.crypto().encryptfollows theroutein the project'sGET /@<slug>/crypto/modeanswer (CryptoMode.route, kept as sent). For BYOK and HYOK only an explicit"server"sends plaintext to the platform (it needs a non-empty epoch, elseK9O_CRYPTO_CUSTODY_UNKNOWN); a missing route or"client"uses your client core. A route that is not"server"or"client"is refused withK9O_CRYPTO_CUSTODY_UNKNOWN(contextcustodyMode, androutewhen it is a string) and nothing is sent, for every custody mode. The mode is read before every encrypt, never cached.crypto().crypts():list,create(name)andretire(name)for the crypt registry (GET/POST /@<slug>/crypto/crypts,POST .../crypts/<name>/retire), returningCrypt(name,status,created_at,retired_at). A bad name is refused withK9O_INVALID_FIELD_VALUE(fieldname) before anything is sent;createsends onlyname; a malformed gateway answer isK9O_INTERNAL_ERROR. 409K9O_CRYPT_ALREADY_EXISTS, 409K9O_CRYPT_LIMIT_EXCEEDED, 409K9O_CRYPT_RETIRED, 404K9O_CRYPT_NOT_FOUNDand access refusals come back as theKError. Retiring only makesencryptrefuse the name;decryptandrewrapnever read the registry. Needscrypto:manage_crypts(PROJECT_ADMIN by default); a personal access token is refused on retire.KiboClientCore: a client core forcrypto()on a BYOK or HYOK project that opens and seals on this machine against your own KMS or HSM. Sequences the federated token, the credential exchange on your cloud and the seal or open, over the newAppCoretrait (the crate does not depend on the Kibo core).FederationSpec::Vaulttakesjwt_auth_mount, the JWT auth mount (jwtforauth/jwt, not the transit mount). Requires a non-emptyexpected_key_refscontaining the configured key; checks the core declaresexpected_key_refsbefore any token is fetched (K9O_CRYPTO_KEY_PIN_UNENFORCED); key, provider, region, role and endpoint come only from your configuration; a token response naming another provider or project is refused; the exchange has a deadline (default 30 s,KIBO_EXCHANGE_TIMEOUT); the credential is cached per crypt, operation and subject until 60 s before expiry; one result or code per item, withUPSTREAM_KMS_ERRORmeaning your own KMS failed.CryptoFederatedTokengains optionalproviderandproject_id.crypto().federated_token(crypt, op)asks for a short-lived token (15 minutes at most) that your own cloud KMS or HSM can trust (POST /@<slug>/crypto/federated-token) and returnsCryptoFederatedToken(token,expires_at,issuer,subject,audience,kid). The crypt andop(encrypt,decrypt,rewrap) are checked before sending; the call is never retried, andDebugredacts the token.crypto():encrypt,decryptandrewrapfor server-side encryption under the project's platform-managed key (POST /crypto/encrypt | decrypt | rewrap). Checks the crypt (a registered name, notactions), the item count and the sizes before sending; one result or code per item, in order; never retried. For service tokens and personal access tokens only (extensions, end users and mobile cannot call it; IAM on the crypt decides, default floor PROJECT_EDITOR). Custody-aware:encryptchecks the project's custody mode on every call (crypto().mode(), never cached) and sends thecustodyEpoch; BYOK and HYOK keys go to a registeredClientCore(crypto().use_client_core), and without one the call raisesK9O_ZK_CLIENT_CORE_UNAVAILABLEand sends no plaintext; an unknown or unreadable mode fails closed.decryptandrewraptry the platform first and reroute client-side on 409K9O_ZK_STORE_FLOW_REQUIREDwith route client. The ciphertext follows the project key's lifecycle only, not per-subject erasure; it is a different construction from client-side Kibo and the extension route.encryptcan answer 404K9O_CRYPT_NOT_FOUND(name not registered) or 409K9O_CRYPT_RETIRED(name retired;decryptandrewrapare not refused for either); both pass through asKError(constantsCODE_CRYPT_NOT_FOUND,CODE_CRYPT_RETIRED). Not live on every gateway yet (a 404 on/crypto/*is expected).ClientOpts.expected_key_refs(Option<Vec<String>>) andkey_ref_matches(KeyRefProvider, key_ref, &expected): for BYOK and HYOK, set the keys you expect from your own cloud configuration.crypto()passes them to the registeredClientCoreon every call in a newCoreOptionsargument (ClientCore::encrypt,decryptandrewrapgainoptions: &CoreOptions<'_>), and the core refuses any other key (version ignored) before it uses a token or makes a network call. A core declares that it does withClientCore::enforces_expected_key_refsreturningtrue(defaultfalse); with the option set and no declaration the call is refused withK9O_CRYPTO_KEY_PIN_UNENFORCEDbefore the core is called. The helper compares by the provider's rule (AWS whole reference; GCP without the version; Azure the first five parts in lower case; Vault<path>/<key>without:<version>); the provider (Aws,Gcp,AzureorVault) is required and never read from the reference.Client::newrejects an empty list, or an entry that is blank, has whitespace or contains*, withK9O_INVALID_FIELD_VALUE.KError.retry_after_sec(Option<f64>): theretryAfterSecnumber from the gateway'srecommendationobject when it is finite and not negative. It is informational; retry behaviour is unchanged.KErrorhas public fields, so code that builds it as a struct literal must addretry_after_sec: None.KError::newis unchanged.approvals().listpages:ListApprovalsOptionsgainscursor, andmeta.cursor.nextof the answer is the cursor of the next page (Noneon the last page). An invalid cursor fails withK9O_INVALID_CURSOR(HTTP 400). Code that buildsListApprovalsOptionsas a struct literal adds..Default::default().approvals().bulkreportsfailed:BulkApprovalsResult.failedlists the rows that matched but could not be decided (BulkApprovalFailure:id,code,reason); it is empty when none failed. The call answers HTTP 200 even when rows fail.require_approval()on single-record writes:from(c).insert_builder(&record),update(..).eq("id", ..)anddelete().eq("id", ..)queue the write for approval (HTTP 202) instead of applying it.executereturns aWriteOutcome:Queuedwith theQueuedChange, orAppliedwith the normal result when anauto_approvepolicy applies the write at once.insertis unchanged; upserts and bulk writes do not take the modifier.functions().triggers():list,create,updateanddeletefor a function's event triggers (collection,events,filter,enabled,log_ok_invocations).deleteanswers 204, sodatais(). The SDK checksevents(1 to 4 ofinsert,update,delete,upsert) and the collection name before sending.schedules():list,get,create,update,delete,runsandrun_nowfor scheduled triggers.listtakesstatus,function_name,limitandcursor. A schedule interval under 5 minutes is rejected with 400K9O_INVALID_FIELD_VALUE(fieldschedule_expression), on every plan.end_users():listandgetfor the project's end users, androle_grants()withlist,grantandrevokefor the roles they hold.roleis any string;listreturns the grants as aVec; revoking an unknown or already revoked grant answersrevoked: falserather than an error.vectors():nearest(collection, &query_vector, NearestOptions { top_k, min_score, metric, filters })andupsert(collection, &rows)for collections of your own embeddings. The vector is sent in the request body (up to 16000 numbers, 1 to 1000 rows per upsert), for a collection of your own embeddings. A collection name must start with_. The SDK checks the name, the vector length and numbers,top_k,metric, the filter values and the row count before sending.metadata():filter,set,search,vectors().nearest,subscribe, andindex().get/index().declarefor the Metadata API. Column names are sent asmetadata.<name>(the prefix is added when missing); the SDK checks surfaces, operators, limits, the 64-column declaration,metric, the embedding and cursor use before sending.filterpages withmeta.cursor.next.searchhas no cursor input,nearestreturns no score and may return at most 50 rows, andsubscribeevents carry only{ collection, id }.subscribeis the change feed ofrealtime().subscribe: it reconnects withLast-Event-ID, drops duplicates and supportson_resync;from_sequenceapplies to the first connection only. ExpectK9O_METADATA_FIELD_NOT_INDEXED,K9O_UNKNOWN_SURFACE,K9O_QUERY_RESULT_TOO_LARGE(413),K9O_NOT_IMPLEMENTED(501 forstorage:surfaces),K9O_ENCRYPTED_COLUMN_OPERATION_UNSUPPORTEDandK9O_EXTENSION_PERMISSION_DENIED.custody().status(): the project's custody mode, attached key provider, last custody job and, for a hardware module, its vendor, cluster and region (CustodyStatus). Read-only.rampart():classify(&input, label),jwks()andverify_receipt(&verdict or receipt, &input, &VerifyOptions).classifyreturns the verdict, the signed receipt exactly as received and theproject_id; Rampart is advisory and a classifier outage is an error (503K9O_RAMPART_CLASSIFIER_UNAVAILABLE), never a pass. 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. 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 newcalibration_version.verify_receiptfetches the key feed (GET /rampart/jwks) itself, caches it for the life of the client and refetches once on an unknownkid. It checkskid,alg,typ, the signature,iss,project_id, theiat/expwindow and the input digest, and refuses with aReceiptRefusal(malformed,key_unknown,alg,typ,signature,issuer,project,project_unknown,expired,not_yet_valid,input_hash,key_feed). The expected issuer is theissuerthe key feed advertises (jwks()returns it next tokeys; theissueroption overrides it); a feed with no issuer and no option is refused asissuer. The expected project is theproject_idoption, else the project id of theClassificationpassed; a bare receipt string with neither is refused asproject_unknown. Ed25519, SHA-256, SHA-512 and the platform's canonical JSON form (jcs_canonicalize: keys sorted by UTF-8 byte order, integers only up to 2^53 - 1, so an input with a fractional number cannot be classified or verified) are implemented in the crate; no dependency was added.analytics()androllups(): datasets.analytics()haslist,query,create,get,delete,materialize,read,write,uploadanddownload_original(the stored original file as bytes), plusrollups()andschedules()withcreate,list,deleteandreattest;rollups()haslist,readandsubscribe(a feed of closed cells with the change feed's reconnect, duplicate drop andon_resync).reattestis for a person only (a service, workload or extension token gets 403K9O_RBAC_DENY,reasonhuman_only); a rollup or schedule that is not re-attested within its 7 to 365 days pauses.keys():list(KeyStatusFilter::Alladds rotating and revoked versions),getandrotatefor the project's encryption keys. Metadata only.rotateneeds project admin and a step-up proof (401K9O_STEP_UP_REQUIREDwithout one), is limited to 3 per rolling 24 hours (429K9O_RATE_LIMITED) and answers 409K9O_STATE_CONFLICTwhile another rotation runs.audit().tail(AuditTailOptions): the live audit feed (audit.project.*, or oneaudit.project.<type>) withtypes,on_resync,reconnect_delayandidle_timeout. Events carryaudit_event_id,event_type,actor_type,occurred_atandoutcome. Areplay-ledgerresync is caught up through the replay endpoint by the tail itself.audit().replay(AuditReplayOptions)wrapsPOST /@<slug>/realtime/replay.VerifiedReceipt.windows: the receipt'swindowsclaim, the number of windows scored (1 when the input fits one window, and for a receipt without the claim). Code that buildsVerifiedReceiptas a struct literal addswindows. Unknown claims are ignored.- 413
K9O_RAMPART_INPUT_TOO_LONGfromrampart().classifyis a typedKError, never a verdict. KError.retry_after_secis also read from aRetry-Afterresponse header when the body gives none.Moat(local, no network, no client): pins the system prompt, refuses role and system markers in untrusted input, enforces an input and an output JSON Schema subset, runs an optional PII filter and givesprompt_sha256(). Refusals areMoatRefusalvalues (role_marker,input_schema,output_schema,pii). Moat finds role markers on a normalised copy of the text (NFKC, combining marks ignored, ignorable characters removed, a small set of Cyrillic and Greek look-alikes of the marker letters read as Latin, case-folded, horizontal whitespace collapsed; not general homoglyph detection), line by line; adds theunicode-normalization0.1.26 dependency.vector_searchon the select builder sends the embedding in the request body.Meta.approval(MetaApproval): the approval status the gateway reports on a queued write.- README sections for writes that wait for approval, function triggers, schedules, vector search and end-user role grants.
- Realtime change feed resumes by itself:
realtime().subscribereconnects withLast-Event-IDafter the server closes the stream (at most 300 seconds) or the network fails, drops events it already delivered byevent_id, ignores:hbheartbeats, abandons a connection that is silent for 45 seconds, and stops onclose(). A 4xx answer on connect is returned once; a 5xx answer is retried with a capped backoff (up to 30 seconds). RealtimeEvent.event_id. Code that buildsRealtimeEventas a struct literal addsevent_id.realtime().subscribe_with(topic, SubscribeOptions)withfilter,on_resync(async, receivesResync { reason, action }),reconnect_delayandidle_timeout. Aresyncframe is no longer returned as an event:on_resyncruns and the subscription continues on a fresh connection withoutLast-Event-ID.Subscription::close().- README: what an event-trigger function receives (the JSON payload, redaction,
triggeredAt, and deduping oneventId).
Fixed
- A gateway error whose
recommendationis an object, for example{"action": "..."}or{"retryAfterSec": 30, "note": "..."}, is no longer turned intoK9O_INTERNAL_ERRORwith no status. The error keeps itscode,message,statusandcontext.recommendationstaysOption<String>: a string is kept, an object gives itsactiontext, else itsnote, and any other JSON type givesNone. compute().llms().listandreadno longer fail with "missing field tierGate".LlmModelnow matches what the gateway sends:id,provider,provider_class,modality,min_tierandinvocableare required;reason,price_in,price_outandprice_unitare optional. The fields the gateway never sent (tier_gate,context_window,capabilities,cost_per_million_input_tokens,cost_per_million_output_tokens) are removed.
1.4.0 — 2026-10-26
Added
query: run one read-only SQL statement with positional or:nameparameters.search: full-text search over one column of a collection.text_searchandvector_searchon the select builder, for full-text and nearest-neighbour search.ai().generate: run a prompt through an LLM, with an optionalmodel. Same result ascompute().llms().invoke.streams():create,list,get,delete,publish,replayandsubscribefor user data streams.subscribereconnects from the last sequence.approvals():list,get,approve,rejectandbulkfor the pending-change queue.approval_policies():list,createanddeletefor the rules that decide which writes are queued.schema().collections().list: the project's collections by name, with cursor paging.
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().createtakesdisplay_name(required) and optionalslug,region,custody_mode.getandupdateuse the projects routes.functions().deploytakesname,runtime,tier(gatewayorsandbox),artifact_key,versionanddescription. Inline code is gone.functions().invokesends{payload}and acceptsInvokeOptions.functions().listacceptslimit,cursor,status,source,tier.- Policies
create,updateandvalidatetake apolicydocument.policies().listtakes onlystatus. audit().queryfilters areevent_type,actor_id,after,before,limit,cursor.- Role grants use
/role-grantsand identity providers use/identity-providers, with typed create and update inputs. default_llm_getanddefault_llm_setreturn records.smtp().settakespassword_refandfrom_address;testtakestoandsubject.api_tokens().createtakeslabel,scope_manifestandttl_seconds.sessions().revokeandrevoke_alluse the session routes.compute().llms().invokeparameters are flat and the result hascontentandusage. Stream chunks are OpenAI-style.workflows().triggersends{triggerContext}.gate().sign_outrequires the refresh token.kibo().vault().secrets().getlooks up a secret by exact name; the region is optional.- The API host is read from the base URL: any
<org>.api.<apex>host works and no domain is built in.
Removed
gate().verify_session,gate().hosted,realtime().replayand the polling transport.me().notifications,me().audit_log,me().data_export.org().groups().create,org().groups().delete,org().members().get,org().smtp().get.- The
modalityfilter ofcompute().llms().listand thetriggerTypefilter ofworkflows().list.
Added
functions().upload_artifact(bytes, "wasm" | "tar")returns theartifact_keyfordeploy.
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.
- 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.