Ruby changelog
Release notes for k9o, from the CHANGELOG.md in the sdk-ruby 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
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, body:, visibility:)andapprovals.comments.list(pending_id, limit: nil, cursor: nil): comment on a pending change (POSTandGET /@<project>/pending-approvals/<id>/comments).bodyis 1 to 4000 characters andvisibilityis"everyone"or"approvers_only", fixed once posted;pending_id,body,visibilityandlimit(1 to 200) are checked before anything is sent (K9O_INVALID_FIELD_VALUE).listanswers the comments the caller may see, oldest first, as a page withnext_cursor(nilon the last page). Posting needs a session; a personal access token alone is refused (K9O_RBAC_DENY).K9O_APPROVAL_COMMENT_NOT_ELIGIBLEandK9O_APPROVAL_COMMENT_CLOSEDarrive asK9o::KError. -
realtime.replay(topic, from_sequence: nil, until_sequence: nil, limit: nil): read a batch of past events for a realtime topic (POST /@<project>/realtime/replay), the catch-up forrealtime.subscribe.topicis required;from_sequenceanduntil_sequenceare whole numbers (0 or more) andlimitis 1 to 10000 (K9O_INVALID_FIELD_VALUEbefore anything is sent).datais{ "events", "nextCursor", "hasMore" }, plus"resync"("reread-source") when the topic keeps no history, so re-read the current state. Events keep the gateway's spelling thatsubscribeyields.audit.replayis unchanged. -
gate.sign_inasks the project which region holds the email first (POST /@<project>/gate/locate, the email only, no credential) and sends the password to that region's host. The located host is used only if it ishttps, has no userinfo, port, path, query or fragment, and is your own org, gateway family and apex with the region code added or swapped in; otherwise the base URL is used. The answer is never cached;refresh_tokenandsign_outgo to the host that issued the session, from a bounded in-memory hint. If the locate step answers 404, the base URL is used. A 429K9O_RATE_LIMITEDor 503K9O_GATE_REGION_UNAVAILABLEfrom that step raises asK9o::KError, nothing else is sent, and the call is safe to retry. -
crypto.modeandcrypto.mode(crypt:)return the gateway'sroute("client"or"server") asMode#route,nilon older gateways or for an unknown value; follow it, notcustody_mode. -
The custody check before each
crypto.encryptnames the crypt (GET /crypto/mode?crypt=<crypt>), so a personal access token or workload policy scoped to named crypts can encrypt.crypto.modesends no query. -
crypto.mode(crypt: nil): an optional crypt for the public mode read (GET /crypto/mode?crypt=<crypt>); the crypt is checked before sending (K9O_INVALID_FIELD_VALUE), andcrypto.modeis unchanged. -
crypto.encryptfollows theroutein the project's mode answer. On a BYOK or HYOK project only an explicit route"server"sends plaintext to the platform (the answer then needs an epoch, otherwiseK9O_CRYPTO_CUSTODY_UNKNOWN); a missing route uses your client core. A route that is not"server"or"client"raisesK9O_CRYPTO_CUSTODY_UNKNOWNand nothing is sent. The mode is read on every call.decryptandrewrapare unchanged. -
crypto.crypts_list,crypto.crypts_create(name)andcrypto.crypts_retire(name): list, register and retire crypt names.createsends only{ name }; a name outside 1 to 64 characters of a-z, 0-9 and-(oractions) raisesK9O_INVALID_FIELD_VALUE(field: name) before anything is sent. Each answers a crypt as{ "name", "status" ("active" or "retired"), "createdAt", "retiredAt" }; a malformed gateway answer raisesK9O_INTERNAL_ERROR.K9O_CRYPT_ALREADY_EXISTS,K9O_CRYPT_LIMIT_EXCEEDED,K9O_CRYPT_RETIRED,K9O_CRYPT_NOT_FOUNDand access refusals arrive asK9o::KError. A retired or unregistered name only makesencryptrefuse it;decryptandrewrapnever read the registry. Needscrypto:manage_crypts(project admins by default); a personal access token is refused on retire. -
K9o::KiboClientCore: the client core fork9o.cryptoon a BYOK or HYOK project. It opens and seals data on this machine against your own KMS or HSM, so the platform never sees plaintext or the key. Register it withcrypto.use_client_core. The key, provider, region, role and endpoint all come from the configuration you pass;expected_key_refs:is required and non-empty, and the configured key must be in it. Before any token is fetched it checks that the bound core listsexpected_key_refs(otherwiseK9O_CRYPTO_KEY_PIN_UNENFORCED) and exports the 2.15.0 functions (otherwiseKIBO_WASM_ERROR). A federated-token response that names another provider or project is refused withK9O_INVALID_FIELD_VALUEand nothing is exchanged. The exchange has a deadline (30 s,exchange_deadline:;KIBO_EXCHANGE_TIMEOUT); the exchanged credential is reused until 60 s before it expires, and a federated token is fetched on every call. A failed item is{ "ok" => false, "code", "message" }with the core's code (UPSTREAM_KMS_ERRORis your own KMS); a pin, capability, token or exchange problem raisesK9o::KError. No token or credential appears in an error,inspectorto_s. A call whose ownexpected_key_refsdoes not contain the configured key is refused per item withK9O_CRYPTO_UNEXPECTED_KEYbefore the federated token is fetched and before the exchange. -
K9o::KiboFfiCore: a built-in bound core forK9o::KiboClientCorethat works with the generated Ruby binding (KiboKmsRestFfi, zk-bundle-v2.16.3 or later). Passcore: K9o::KiboFfiCore.new. It converts the SDK's plain data to the binding's typed records, integer enums and federation variant, and the binding's errors toCODE: detail(UPSTREAM_KMS_ERRORfor your own KMS failing); the cryptography stays in the native core. Requiringk9odoes not load the binding; building the adapter without it raisesK9o::KError(KIBO_WASM_ERROR).library:takes the absolute path of the native library,binding_path:the path of the binding file. The Vault federation field for the JWT login isjwt_auth_mount(the name Vault serves the JWT login under,jwtforauth/jwt; not the transit mount); the core receives it as its ownmountfield, andvault_addr,jwt_auth_mountandroleare required forprovider: "vault". -
K9o::Crypto::FederatedToken#providerand#project_id: set when the gateway names them in the federated-token response, otherwisenil. They are only checked against your configuration. -
crypto.federated_token(crypt, op): ask for a short-lived RS256 token (valid for at most 15 minutes) for one crypt and one operation ("encrypt","decrypt"or"rewrap"), answered asK9o::Crypto::FederatedToken(token,expires_at,issuer,subject,audience,kid).cryptandopare checked before sending (K9O_INVALID_FIELD_VALUE); the call is never retried; a response without any of the six fields raisesK9O_INTERNAL_ERROR. The token is left out ofinspect,to_sandpp. -
expected_key_refs:client option: anArrayof the key identifiers (from your own cloud configuration) your BYOK or HYOK key may be. It is checked when the client is built (non-empty, no blanks, spaces or*;K9O_INVALID_FIELD_VALUEotherwise) and passed to the client core as the keywordexpected_key_refs:on everycrypto.encrypt,decryptandrewrapcall when set, so the core refuses any other key (version ignored) before it uses a token or makes a network call. A core declares that it does with a methodenforces_expected_key_refs?that returnstrue; with the option set and no declaration the call raisesK9O_CRYPTO_KEY_PIN_UNENFORCEDbefore the core is called.K9o::Crypto.key_ref_matches?(key_ref, expected, provider:)is the comparison for core authors (provider:is required, one of:aws,:gcp,:azureor:vault, and is never guessed from the reference): AWS compares the whole reference; GCP without the version; Azure the first five parts in lower case; Vault<path>/<key>without:<version>. -
custody.status: read how the project's keys are held (mode,attached,provider,lastJob, andhsmfor a hardware security module); read-only. -
KError#retry_after_sec: the wait the gateway asks for (seconds), ornil. -
KError#request_idis filled from the gateway'sx-k9o-request-idresponse header (any letter case) when the error body carries no request id, on every error built from a non-2xx response, including a stream open; a request id in the body still wins, and it staysnilwhen neither is present. -
require_approvalon single-record writes:insert(record, require_approval: true), and.require_approvalonupdateanddeletebuilders. The write is sent with?requireApproval=trueand may answer a queued change (HTTP 202);K9o.queued_write?(result)tells it from an applied row.Meta#approvalcarriesmeta.approval. -
functions.triggers:list,create,updateanddeletefor event triggers. -
schedulesnamespace:list,get,create,update,delete,runsandrun_now. -
vectorsnamespace:nearestandupsertfor vector collections (names start with_), sending the embedding in the request body. -
metadatanamespace:filter,set,search,vectors.nearest,subscribe, andindex.get/index.declarefor the columns you declare on a collection. Column names inwhere,searchandnearestget themetadata.prefix when you leave it out;setwrites declared columns only.subscribeuses the same reconnecting reader asrealtime.subscribe(events carry the record id only) and takesfrom_sequence:. The SDK checks the surface grammar, limits, cursor rule and the 64-column limit before sending. Gateway codes such asK9O_METADATA_FIELD_NOT_INDEXED,K9O_UNKNOWN_SURFACEandK9O_QUERY_RESULT_TOO_LARGEarrive asK9o::KError. -
rampartnamespace:classify(input, label:)answers the verdict and its signed receipt (advisory; a classifier outage raisesK9O_RAMPART_CLASSIFIER_UNAVAILABLE),jwksreads the public key feed, andverify_receipt(result_or_receipt, input)checks a receipt locally (EdDSA,typ, issuer, project, clock skew, and the SHA-256 of the canonicalinput) and returns the verified verdict or raisesK9o::Rampart::ReceiptRefusalwith a closedreason. The issuer comes from the key feed (issuer:overrides it); the project is theprojectIdof theclassifyresult (orproject_id:), and a bare receipt string with neither is refused asproject_unknown. Keys are cached for the client's life and refetched once on an unknown key id.K9o::Jcs(the platform's canonical form: 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) andK9o::Ed25519(openssl, with a built-in fallback) are included, with no new dependency. A long input is scored in overlapping windows and the highest injection score decides; past 16 windows (about 6,000 tokens) the answer is413 K9O_RAMPART_INPUT_TOO_LONGwith no verdict, and503 K9O_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. -
analyticsnamespace for datasets:list,query,create,get,delete,materialize,read(cursor paging),write,upload(raw or multipart with a manifest),download_original(answers aK9o::Download), plusanalytics.rollupsandanalytics.schedules(create,list,delete,reattest) and the project-widerollupsnamespace (list,read,subscribe).reattestis for people only: a service, workload or extension token gets403 K9O_RBAC_DENY(reason: human_only), and a rollup or schedule that is not re-attested pauses when its interval ends. -
keysnamespace:list,getandrotatefor the project's encryption keys (metadata only;listtakesstatus:activeoralland is not paged).rotate(key_id, step_up: hook): on401 K9O_STEP_UP_REQUIREDthe SDK calls your hook with the challenge (KError#step_up), the HTTP method and the URL, sends the same request once more with thex-k9o-step-up-proofheader built from its{ method:, proof: }answer, and never loops; without a hook the error carries the challenge. Rotation is never retried otherwise, and answers409 K9O_STATE_CONFLICTor429 K9O_RATE_LIMITED(at most 3 per rolling 24 hours) asK9o::KError. -
audit.tail(types:, on_resync:): live audit events (auditEventId,type,actorType,occurredAt,outcome, and the frame'seventId) read from the gateway's frames (the audit event sits inpayload; the frame's SSEidis the publisher's own id and theLast-Event-IDfor a resume), on the reconnecting reader ofrealtime.subscribe; on areplay-ledgerresync it reads the missed events through the newaudit.replayafter the lastauditEventIddelivered, page by page, and yields them once.audit.replayanswers the typed page{ events, nextCursor, hasMore }(events flattened,sequencea string). -
audit.tailafter aresyncis gapless: it reconnects fresh and buffers that connection, replays from the last deliveredauditEventId, then merges replay, buffered and live frames, each event once (a repeated resync backs off).audit.replaysendslimit: 1000when you give none and refuses a limit above 10000 or below 1 withK9O_INVALID_FIELD_VALUE. A new connection starts at the live head and may re-send the last few seconds of events (each yielded once), and the informationalresyncthat opens it is ignored. -
rollups.subscribeyields the cell from eachcellframe'spayload(witheventIdand asuppressedflag for cells below the cohort threshold), resumes with the frame'sid, and callson_resynconreread-source. -
cryptonamespace for server-side encryption with the project's key:encrypt,decryptandrewrap(POST /crypto/encrypt|decrypt|rewrap), batches of up to 100 items, bytes in and out with the base64 done for you,K9o::Crypto.text, and client-side checks (K9O_INVALID_FIELD_VALUE,K9O_PAYLOAD_TOO_LARGE) before anything is sent. Never retried automatically.encryptchecks the custody mode (crypto.mode) on every call and never sends plaintext when the key is in your own KMS or HSM;decryptandrewraptry the platform first and reroute client-side on409 K9O_ZK_STORE_FLOW_REQUIRED. Register the Kibo client core withcrypto.use_client_core; without one those calls raiseK9O_ZK_CLIENT_CORE_UNAVAILABLE(501). An unknown mode or a failed check raises and sends nothing. The gateway route is not live yet. -
Rampart::Verdict#windows: the number of windows the classifier scored, read from the signedwindowsclaim (nilwhen absent); unknown claims are ignored.413 K9O_RAMPART_INPUT_TOO_LONGraises asK9o::KError. -
KError#retry_after_secalso reads theRetry-Afterresponse header (whole seconds) when the body gives none. -
K9o::Moat: a local guard for one model call with no network access. It pins the system prompt, refuses role and system markers in untrusted input, checks input and output against a documented JSON Schema subset, and runs an optional PII filter you pass in. Refusals raiseK9o::Moat::Refusalwithreasonrole_marker,input_schema,output_schemaorpii. -
K9o::Moatrole-marker scan follows the shared normalisation rule: NFKC, combining marks ignored, default-ignorable and format code points removed, 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, then matched line by line; it passes the shared marker vectors. -
end_usersnamespace:list,getandrole_grants(list,grant,revoke). -
approvals.listpages: optionalcursor:(frommeta.cursor.next,nilon the last page) besidestatus:andlimit:. -
approvals.bulkresult carriesfailed, a list of{ "id", "code", "reason" }for rows that did not apply (empty when none); the call answers HTTP 200 even when rows fail. -
realtime.subscriberesumes: it reconnects withLast-Event-IDwhen the stream ends or the network fails (backoff up to 30 seconds), drops duplicate events byeventId, ignores heartbeats, abandons a connection idle for 45 seconds, and calls the new optionalon_resync:handler (without yielding the frame) before continuing from a fresh connection. Events carryeventId. -
README: what an event-trigger function receives (the JSON payload, redaction,
triggeredAt, and deduping oneventId).
Changed
-
The read timeout is 120 seconds (was 30), as in the Python SDK, so a long call such as Rampart
classifyon a long input is not cut off. A client you pass in withhttp_client:keeps being set to the same value. -
vector_searchon the select builder sends the embedding in the request body (POST data/<collection>/search), so real embeddings work. It cannot be combined withtext_search. -
The approval policies README no longer says the builders do not send
requireApproval.
Fixed
-
realtime.subscribe,metadata.subscribeandrollups.subscribeno longer reconnect forever on a fresh connection. The gateway opens such a connection with an informationalevent: resyncframe and then streams events on the same connection; the reader treated that frame as a lost position, so no event was delivered. Aresyncthat is the first data of a connection sent with noLast-Event-IDand nofromSequenceis now ignored (on_resyncis not called and the connection is kept). Aresyncafter an event, or on a connection sent withLast-Event-IDorfromSequence, is still a lost position:on_resyncis called and the reader reconnects fresh.audit.tailis unchanged. -
require "k9o"no longer fails on Ruby 3.4 and later withcannot load such file -- base64: the vault code encodes and decodes base64 without thebase64gem, which is no longer a default gem there and was not declared as a dependency. -
audit.tailandaudit.replayread the gateway's real frames: the tail used to deliver no events, and a replay returned an empty list, because the decoders looked for the five audit fields at the top of the frame and took the SSEidfor the audit event id.rollups.subscribeyielded the frame, not the cell. -
Rampart#classifyraisesK9O_INVALID_FIELD_VALUEfor aninputthat is not a Hash, with a test; the gateway is going to refuse it with a 400. -
keys.listno longer exposesnextCursor(the list is not paged). -
KError#recommendationis always a string ornil. An object recommendation from the gateway ({"action": ...}or{"retryAfterSec": ..., "note": ...}) used to arrive as a Hash; it now gives itsaction, else itsnote.
1.4.0 — 2026-10-26
Added
-
query(sql, params): one read-only SQL statement; an array binds$1, $2, ..., a hash binds:nameplaceholders. -
search(collection, column:, q:): full-text search over one column, plustext_searchandvector_searchonselect. -
ai.generate: text generation from a prompt (verb sugar overcompute.llms.invoke;modeldefaults to the org's default LLM). -
streamsnamespace for user data streams:create,list,get,delete,publish,replayandsubscribe.subscribetails live events over SSE and reconnects from the last sequence when the server closes the connection. -
approvalsnamespace for the pending-change queue:list,get,approve,rejectandbulk. -
approval_policiesnamespace:list,createanddelete. -
schema.collections.list: the project's collections with row counts and last migration, paged by cursor.
Changed
- The README description now covers streams and realtime, and the platform overview moved to an "About Kilimanjaro" appendix.
- Function deploy examples use the sandbox tier.
1.3.0 — 2026-10-26
Every method now matches the gateway.
Changed
projects.createtakesdisplay_name:(and optionalslug:,region:,custody_mode:, ...);projects.getandprojects.updateuse the projects routes.functions.deploytakesname:,runtime:,tier:(gatewayorsandbox),artifact_key:,version:anddescription:. Inline code is gone.functions.invokesends the payload as{payload}.policies.create,updateandvalidatetake apolicy:document (plus optionalrules:,editor_mode:);policies.listtakes onlystatus:.audit.queryfilters areevent_type:,actor_id:,after:,before:,limit:andcursor:.- Org roles, identity providers and default model use the current routes;
smtp.setusespassword_ref:andfrom_address:;smtp.testtakesto:andsubject:. me.api_tokens.createtakeslabel:andscope_manifest:(andttl_seconds:);me.sessions.revokeandrevoke_alluse new routes.compute.llms.invokesettings are sent flat, and the result hascontentandusage.studio.workflows.triggersends the context astriggerContext.gate.sign_outrequires the refresh token.- The API host comes from the base URL: any
<org>.api.<apex>host works and no apex is hardcoded.https://api.k9o.iois only the default.
Removed
gate.verify_session,gate.hosted,realtime.replayandrealtime.subscribe_poll.me.notifications,me.audit_logandme.data_export.org.groups.create,org.groups.delete,org.members.getandorg.smtp.get.
Added
functions.upload_artifact(bytes, kind)uploads a build and returns theartifactKeyfordeploy.UrlGrammar.parse_api_hostreads the org, region and apex from any gateway host.- A contract test checks every method against the gateway's API description.
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.