Java changelog
Release notes for dev.k9o:core, from the CHANGELOG.md in the sdk-java 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():add(pendingId, body, visibility)(POST /@<project>/pending-approvals/<id>/comments) andlist(pendingId, limit, cursor)(GETon the same path, oldest first).addanswersApprovals.Comment(id,caseId,authorId,visibility,body,createdAt);listanswersApprovals.CommentPage, anEnvelopewithnextCursor().bodyis 1 to 4000 characters andvisibilityiseveryoneorapprovers_only(Approvals.VISIBILITY_EVERYONE,Approvals.VISIBILITY_APPROVERS_ONLY); both andpendingIdare checked before sending (K9O_INVALID_FIELD_VALUE). Posting needs a session. Gateway refusals pass through asKError:K9O_APPROVAL_COMMENT_NOT_ELIGIBLE,K9O_APPROVAL_COMMENT_CLOSED,K9O_NOT_FOUND,K9O_RBAC_DENY. -
realtime().replay(topic, options): read the events recorded on a realtime topic in order (POST /@<project>/realtime/replay;Realtime.ReplayOptionsfromSequence,untilSequence,limit1 to 10,000). ReturnsRealtime.ReplayPage(eventsasRealtime.RealtimeEvent,nextCursor,hasMore,resync).Realtime.RealtimeEventgainssequence()(a string; set only on replayed events; the five-argument constructor still works).audit().replayis unchanged. -
gate().signInfirst asks the project which region holds the email (POST /@<project>/gate/locate, only the email, no credential), then sends the password to the origin it names. The SDK uses that origin only if it ishttpswith no user info, port, path, query or fragment, and is a region host of the same organization, gateway family and domain as the client's base URL whose region code matches the answer; otherwise it uses the base URL. Nothing is cached except a bounded in-memory hint (64) per refresh token, read byrefreshTokenandsignOutand removed on sign-out. If the locate step answers 404, the base URL is used. Any other non-2xx answer from that step (429K9O_RATE_LIMITED, 503K9O_GATE_REGION_UNAVAILABLE) is raised as the usualKError(Gate.RATE_LIMITED,Gate.REGION_UNAVAILABLE), the password is not sent and nothing is retried. -
crypto().mode()andcrypto().mode(crypt)return the gateway'sroute("client"or"server") asCrypto.Mode.route(),nullon older gateways or for an unknown value; follow it, notcustodyMode. The two-argumentModeconstructor still works. -
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.mode()sends no query. -
crypto().mode(crypt): an optional crypt for the public mode read (GET /crypto/mode?crypt=<crypt>); the crypt is checked before sending (K9O_INVALID_FIELD_VALUE), andmode()is unchanged. -
crypto().encryptfollows theroutefield of the project's mode answer. On BYOK or HYOK only an explicit"server"sends plaintext to the platform (an epoch is required, elseK9O_CRYPTO_CUSTODY_UNKNOWN); a missing route means the client core. A route that is neither"server"nor"client"is refused withK9O_CRYPTO_CUSTODY_UNKNOWN(contextcustodyMode, androutewhen it is a string) in every custody mode, and nothing is sent. The mode is read before every encrypt.decryptandrewrapare unchanged. -
expectedKeyRefs(List<String>)client option for BYOK and HYOK: the router passes it to the registeredCrypto.ClientCoreon everyencrypt,decryptandrewrapas a newCrypto.CoreOptionsargument (an empty list when not set), and the core must refuse a key that is not in it before it uses any token or makes any network call. Checked atbuild(): not empty, no blank entry, no whitespace, no*(K9O_INVALID_FIELD_VALUE, fieldexpectedKeyRefs). A core declares that it enforces the pin withClientCore.enforcesExpectedKeyRefs()(defaultfalse); with the option set and no declaration the call is refused withK9O_CRYPTO_KEY_PIN_UNENFORCED(Crypto.KEY_PIN_UNENFORCED, no HTTP status) before the core is called.Crypto.keyRefMatches(keyRef, expected, provider)compares by the provider's rule (Crypto.KeyRefProvider: AWS whole reference; GCP without the version; Azure the first five parts in lower case; Vault<path>/<key>without:<version>). The provider is required and never guessed from the reference, because a Vault reference can look like a URL. The threeClientCoremethods take theCoreOptionsargument. -
rampart():classify(input, label)classifies a JSON object (POST rampart/classify) and returns the verdict with the signed receipt as received and theprojectId;jwks()reads the public key feed (GET /rampart/jwks:keysandissuer);verifyReceipt(result, input, options)takes the classify result or a bare receipt string and verifies the receipt (key bykid,EdDSA,typ, signature, issuer from the key feed or theissueroption, project from theprojectIdoption or the classify result, clock skew, and the SHA-256 of the input canonicalised with the platform's JCS code-point profile: keys sorted by UTF-8 byte order, integers only up to 2^53-1) and returns the signed claims, or throwsRampart.ReceiptRefusalwith a closedreason(malformed,key_unknown,alg,typ,signature,issuer,project,project_unknown,expired,not_yet_valid,input_hash). Keys are cached for the client's life and refetched once on an unknownkid. Rampart is advisory: it never blocks, and an unavailable classifier 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 newcalibrationVersion. -
Rampart.VerifiedReceipt.windows(): the signedwindowsclaim, the number of windows the classifier scored (1 when the input fits one window; a receipt without the claim reads as 1). Unknown claims in a receipt are ignored. A 413K9O_RAMPART_INPUT_TOO_LONGis aKError(Rampart.INPUT_TOO_LONG), never a verdict. -
analytics(): datasets.list,create,get,delete,write(onErrorskip or reject),upload(CSV or JSON up to 25 MiB; raw body, or multipart with amanifestthat creates the dataset),downloadOriginal(bytes and content type),materialize(from a collection or a saved query),query(read-only SQL over datasets) andread(rows bycursor,limit,partitionFilter), plusrollups()andschedules()(create,list,delete,reattest). A rollup or schedule keeps running only while it is re-attested within 7, 30, 90 or 365 days;reattestis people only (a service, workload or extension token gets 403K9O_RBAC_DENY, reasonhuman_only). -
rollups():list,read(cells of a time range; cells below the cohort threshold read as suppressed) andsubscribe, a server-sent events feed that yieldsRollups.Cell(cellKey,bucket,dims,isFinal(),measures,eventId,occurredAt; a cell below the cohort threshold hassuppressed(),statusandreason). It resumes with the frameidasLast-Event-ID(fromSequenceon the first connection), drops resent cells byeventId, reopens after the 300-second connection limit and passes areread-sourceresync toonResync. -
keys(): the project's key inventory, metadata only.list()(the active key) andlist(true)(every version),get(keyId)androtate(keyId)(the list is not paged:Keys.Pagehasitemsonly);Keys.Keyhasid,version,status,custodyMode,createdAt,rotatedAt,byokRefandhyokRef. Rotation needs the project admin role and a fresh step-up proof, is limited to 3 per rolling 24 hours (429K9O_RATE_LIMITED,retryAfterSec()), and refuses a second one at a time (409K9O_STATE_CONFLICT). -
audit().tail(options): follow the project's audit log live (auditEventId,type,actorType,occurredAt,outcomeflattened from the frame's payload, plus the frame'seventId), withtypes, the change-feed behaviour ofrealtime().subscribe(resume with the SSEid, dedupe, idle timeout) and, on areplay-ledgerresync, a paged catch-up through the newaudit().replay(opts)(afterAuditEventIdorfromSequence; returnsAudit.ReplayPagewithevents,nextCursor,hasMore;sequenceis a string) and a reconnect withLast-Event-ID.warden.checkpointis not in the live tail. -
audit().tailresync is gapless: after areplay-ledgerresync the tail reconnects fresh (noLast-Event-ID) first, then replays from the last deliveredauditEventId, then merges the connection's frames, each event once; a second resync in a row backs off.audit().replaywithoutlimitsendslimit: 1000(an explicit limit up to 10,000 is passed as given). -
keys().rotate(keyId, Keys.RotateOptions.withStepUp(hook)): on 401K9O_STEP_UP_REQUIREDthe hook receives the challenge (scopeSetRoot,nonce,methods,maxAgeSec,rpId) with the HTTP method and URL and returnsKeys.StepUpProof(method, proof); the SDK sends thex-k9o-step-up-proofheader and retries exactly once. Without a hook the challenge is onKError.getStepUp(). -
crypto(): server-side encryption,encrypt,decryptandrewrap(POST crypto/encrypt,crypto/decrypt,crypto/rewrap) in batches of 1 to 100 items under a crypt, with bytes and UTF-8 helpers, base64 handled for you, client-side checks of the crypt (a registered name, 1 to 64 characters of a-z, 0-9 and -, notactions), item count, context and sizes (K9O_INVALID_FIELD_VALUE,K9O_PAYLOAD_TOO_LARGE), aCrypto.Resultper item and no automatic retry. Machine calls for service tokens and personal access tokens only; IAM on the crypt decides; it routes by custody:encryptcheckscrypto().mode()(custodyMode,epoch) on every call, sendscustodyEpoch, never sends plaintext to the platform for a BYOK or HYOK project and re-checks once on a 409K9O_ZK_STORE_FLOW_REQUIRED; an unknown, missing or malformed mode answer raisesK9O_CRYPTO_CUSTODY_UNKNOWN(Crypto.CUSTODY_UNKNOWN, no HTTP status) and a failed mode call rethrows its own error, neither sending anything;decryptandrewrapreroute to the client core when the platform answers that 409 with routeclient;crypto().useClientCore(Crypto.ClientCore)registers the Kibo client core, and without one those calls throwK9O_ZK_CLIENT_CORE_UNAVAILABLE(501); the ciphertext follows the project key's lifecycle and is not covered by per-subject erasure; it is a different construction from client-side Kibo and fromk9o.kibo.encrypt. Not live on the gateway yet (404 expected). -
crypto().federatedToken(crypt, op): a token forencrypt,decryptorrewrapon a crypt (POST crypto/federated-token), valid at most 15 minutes, returned asCrypto.FederatedToken(token,expiresAt,issuer,subject,audience,kid, andproviderandprojectIdwhen the gateway sends them,nullotherwise). 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. -
crypto():listCrypts()(GET crypto/crypts),createCrypt(name)(POST crypto/crypts, body is onlyname) andretireCrypt(name)(POST crypto/crypts/<name>/retire, no body), returningCrypto.Crypt(name,statusactiveorretired,createdAt,retiredAtornull). A bad name (the crypt rule) is refused before sending withK9O_INVALID_FIELD_VALUE, fieldname. An answer with no crypts list, an unknown status, no name or createdAt, or a retiredAt that is neither a date nor null raisesK9O_INTERNAL_ERROR. Gateway refusals pass through asKError:K9O_CRYPT_ALREADY_EXISTSandK9O_CRYPT_LIMIT_EXCEEDED(Crypto.CRYPT_ALREADY_EXISTS,Crypto.CRYPT_LIMIT_EXCEEDED, 409),K9O_CRYPT_RETIRED,K9O_CRYPT_NOT_FOUND,K9O_ACCESS_DENIED,K9O_IAM_POLICY_DENIED,K9O_RBAC_DENY. A retired or unregistered name only makesencryptrefuse it;decryptandrewrapnever read the registry. Create and retire needcrypto:manage_crypts(project admin by default); any personal access token is refused on retire. -
rampart().classify(Object input, label): refuses an input that is not a JSON object withK9O_INVALID_FIELD_VALUEbefore sending. -
KError.retryAfterSec()is also filled from aRetry-Afterheader given in seconds when the error body carries none. Retry timing is not affected. -
Jcs.canonicalize(value): the platform's JCS code-point profile (keys sorted by UTF-8 byte order, integers only up to 2^53-1), in the SDK. -
Moat: pins the system prompt (messages(input)builds the list; untrusted input is always ausermessage), refuses role and system markers, enforces an input and an output schema (a JSON Schema subset checked in the SDK), runs an optional PII filter on output, and givespromptSha256(). It runs locally with no network access. The pin is structural: it stops injected text from becoming the system prompt and does not stop it reaching the model. -
Moatrole-marker scan: before matching, the text is normalised with NFKC, combining marks are ignored, default-ignorable and format code points are removed, a small set of Cyrillic and Greek look-alikes of the marker letters are read as the Latin letter (not general homoglyph detection), it is case-folded and horizontal whitespace is collapsed (line breaks kept); the text sent to the model is unchanged. Checked against the shared marker vectors. -
KError.retryAfterSec(): theretryAfterSecnumber of the error'srecommendationobject,nullwhen absent. A new seven-argument constructor takes it; the six-argument one is unchanged. Retry timing is not affected. -
approvals().list(status, limit, cursor): pages through the queue; the cursor of the next page ismeta().cursor().next(),nullon the last page. A bad cursor fails withK9O_INVALID_CURSOR. -
Approvals.BulkResult.failed(): the rows abulkcall could not decide, asApprovals.BulkFailure(id,code,reason). The call answers 200 even then; an absentfailedreads as an empty list. -
requireApproval()on single-recordinsert,updateanddelete(from("orders").insert(record).requireApproval().execute(Row.class)): the write is queued for approval (HTTP 202) instead of applied. The result is aGatedWrite:Queuedwith the queued change (Approvals.QueuedChange) or, when anauto_approvepolicy applies the write at once,Appliedwith the normal result;isQueued()tells them apart. Upserts and bulk writes do not take it.from(c).insert(record)without a row class now returns the insert builder;insert(record, Row.class)is unchanged. -
Envelope.Meta.approval(): themeta.approvalobject of a queued write. -
functions().triggers():list,create,updateanddeletefor a function's event triggers (collection,events,filter,enabled,logOkInvocations).deleteanswers 204, sodata()isnull. The SDK checksevents(1 to 4 ofinsert,update,delete,upsert) and the collection name before sending. -
schedules():list,get,create,update,delete,runsandrunNowfor scheduled triggers.listtakesstatus,functionName,limitandcursor. A schedule interval under 5 minutes is rejected with 400K9O_INVALID_FIELD_VALUE(fieldschedule_expression), on every plan. -
endUsers():listandgetfor the project's end users, androleGrants()withlist,grantandrevokefor the roles they hold.revokeanswersrevokedfalse, not an error, for an unknown or already revoked id. -
vectors():nearest(collection, queryVector, options)andupsert(collection, rows)for collections of your own embeddings.optionsis aVectors.NearestOptions(topK,minScore,metric,filters). The vector is sent in the request body (up to 16000 numbers, 1 to 1000 rows per upsert), as the builder'svectorSearchnow does. A collection name must start with_. The SDK checks the name, the vector length and numbers,topK,metricand the row count before sending. -
vectorSearchon the select builder sends the embedding in the request body (POST data/<collection>/search), so real embeddings work. It cannot be combined withtextSearch. Rows returned are the smaller oflimit(default 50) and the vector limit (default 10). -
custody().status(): read-only custody status of the project (mode,attached,provider,lastJob,hsm) fromGET custody/status. A missinghsmreads asnull. -
metadata(): the Metadata API. Declare columns on a collection, then read and change them through one API with the same access rules as the data.filter(input)(POST metadata/query) reads one or more surfaces (collection:<name>,telemetry:<event>,storage:<bucket>) withwhereconditions,limit(1 to 1000) and acursor(one surface only; the next cursor ismeta().cursor().next()).set(collection, id, metadata)writes declared columns and returns the updated record.search(input)is full-text search over a declared text column (first page only, no rank).vectors().nearest(input)finds the rows nearest to an embedding (no score; at most 50 rows come back whateverkis).subscribe(surface, options)follows a collection live over the reconnecting change feed (Last-Event-ID,eventIdde-duplication,onResync); events carrycollectionandidonly, andfromSequenceis used on the first connection only.index().get(collection)andindex().declare(collection, columns)read and replace the declaration (at most 64 columns). Column names are sent asmetadata.<name>; the prefix is added when missing (not forcreatedAtandactorIdon atelemetry:surface), andsetdrops a leadingmetadata.from keys. The SDK checks surfaces, operators,limitandk(1 to 1000),metric, the embedding, the column count and cursor use before sending. Gateway errors arrive asKError:K9O_METADATA_FIELD_NOT_INDEXED,K9O_UNKNOWN_SURFACE,K9O_QUERY_RESULT_TOO_LARGE(413),K9O_NOT_IMPLEMENTED(501,storage:surfaces),K9O_ENCRYPTED_COLUMN_OPERATION_UNSUPPORTEDandK9O_EXTENSION_PERMISSION_DENIED. -
Realtime change feed resume:
realtime().subscribereconnects when a connection ends (the gateway closes each after at most 300 seconds) or fails, sendingLast-Event-IDwith the lasteventId, and drops events it already delivered (latest 1024 remembered). Delays follow the gateway'sretry:hint (1 second by default) and back off to 30 seconds on repeated failures; a 4xx on connect is thrown once, a 5xx or network error is retried. Iteration ends when you close the stream. -
RealtimeEvent.eventId(). -
realtime().subscribe(topic, filter, options)withRealtime.SubscribeOptions:onResync(called with aRealtime.Resyncofreasonandactionwhen the gateway reports a lost position; the stream then reconnects withoutLast-Event-ID),idleTimeout(default 45 seconds without bytes) andreconnectDelay. -
README: what an event-trigger function receives (the JSON payload, redaction,
triggeredAt, and deduping oneventId).
Changed
- A realtime stream no longer ends when the server closes the connection; it reconnects. Stop iterating by closing the stream or breaking out of the loop.
Fixed
realtime().subscribe,metadata().subscribeandrollups().subscribeno longer reconnect in a loop without delivering anything. On a connection opened withoutLast-Event-IDthe gateway sends aresyncframe (cursor-evicted) before the events; the stream now treats that first frame as informational (no reconnect,onResyncnot called) and keeps reading the same connection. Aresyncafter an event, or on a connection that sentLast-Event-IDorfromSequence, is still a lost position and behaves as before.audit().tailis unchanged.- A gateway error whose
recommendationis an object (for example{"action": "..."}or{"retryAfterSec": 30, "note": "..."}) now keeps its text ingetRecommendation()(theaction, else thenote) instead of dropping it. Any other JSON type in that field reads asnull; the error always decodes. This covers both ordinary responses and the SSE stream open. KError.getRequestId()is filled from thex-k9o-request-idresponse header (any case) on every error built from a response, including a non-KError body, a stream open, a download and the key feed, when the error body carries norequestId; a body value wins. Success responses are unchanged.
1.4.0 — 2026-10-26
Added
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.query(sql, params): run one read-only SQL statement.paramsis aList(positional) or aMap(named:nameplaceholders, rewritten to$n).search(collection, input): 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():list,get,approve,rejectandbulkfor the pending-change queue.approvecan answer withstatusstillpending_approval;listis not paginated;bulkskips failed rows silently, so compareaffectedIdswith what you intended.approvalPolicies():list,createanddeletefor the rules that decide which writes are queued.schema().collections().list(limit, cursor): list the project's collections by name, withmeta().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().createtakesProjects.CreateInputwithdisplayName(required) and optionalslug,region,custodyMode.getandupdateuse the projects routes.functions().deploytakesname,runtime,tier(gatewayorsandbox),artifactKey,versionanddescription. Inline code is gone.functions().invokesends{payload}and acceptsFunctions.InvokeOptions.functions().listacceptslimitandcursor.- Policies
create,updateandvalidatetake aPolicies.PolicyInputdocument.policies().listtakes onlystatus. audit().queryfilters areeventType,actorId,after,before,limit,cursor.- Role grants use
/role-grantsand identity providers use/identity-providers, with a typedCreateIdpInput. org().defaultLLM()returns an object.org().smtp().settakespasswordRefandfromAddress;testtakestoandsubject.me().apiTokens().createtakeslabel,scopeManifestandttlSeconds.me().sessions().revokeandrevokeAlluse the session routes.compute().llms().invokeparameters are flat and the result hascontentandusage. Stream chunks are OpenAI-style.RealtimeEventis{topic, eventType, payload, occurredAt}.studio().workflows().triggersends{triggerContext}.- Optional fields left
nullare no longer sent. - The API host is read from the base URL: any
<org>.api.<apex>host works and no domain is built in.
Removed
gate().verifySession,gate().hosted,realtime().replayandrealtime().subscribePoll.me().notifications(),me().auditLog(),me().dataExport().org().groups().create,org().groups().delete,org().members().get,org().smtp().get.- The
modalityfilter ofcompute().llms().listand thetriggerTypefilter ofstudio().workflows().list.
Added
functions().uploadArtifact(bytes, "wasm" | "tar")returns theartifactKeyfordeploy.
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.