TypeScript changelog
Release notes for @k9o/core, from the CHANGELOG.md in the sdk-typescript 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
tierGate, 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(id, { body, visibility })(POST /@<project>/pending-approvals/<id>/comments) andapprovals.comments.list(id, { limit?, cursor? })(GETon the same path): comments on a pending change.bodyis plain text of 1 to 4,000 characters andvisibility(everyoneorapprovers_only) is required and fixed when posted; a bad value is refused withK9O_INVALID_FIELD_VALUEbefore sending.listis oldest first and returns{ data, nextCursor, meta }. Posting needs a session.ApprovalComment,ApprovalCommentVisibility,ApprovalCommentPage,AddApprovalCommentInputandListApprovalCommentsOptionsare exported.realtime.replay(topic, options?)(POST /@<project>/realtime/replay): one call of a topic's ledger catch-up, next torealtime.subscribe. The topic is required; optionsfromSequence,untilSequence,limit(1 to 10000) andafterAuditEventId(audit topics). Returns{ topic, events, nextCursor, hasMore, resync? }with events in the realtime shape plussequence.RealtimeReplayOptions,RealtimeReplayPageandRealtimeReplayEventare exported.audit.replayis unchanged.schema.collections.get(name)(GET /@<project>/schema/collections/<name>): one collection with its columns, indexes and relationships.CollectionDetail,CollectionColumn,CollectionIndexandCollectionRelationshipare exported.crypto.mode()andcrypto.mode(crypt)return the gateway'sroute("client"or"server") on the result asCryptoMode.route, absent on older gateways or for an unknown value; follow it, notcustodyMode.- 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(crypt?)takes an optional crypt and sends?crypt=<crypt>; a bad crypt is refused withK9O_INVALID_FIELD_VALUEbefore sending. With none it is unchanged.crypto.encryptfollows theroutefield of the project's mode answer (GET /crypto/mode). For BYOK and HYOK only an explicitroute: "server"sends plaintext to the platform (it needs anepoch, otherwiseK9O_CRYPTO_CUSTODY_UNKNOWN); a missingrouteor"client"uses the client core. Aroutethat is neither"server"nor"client"is refused withK9O_CRYPTO_CUSTODY_UNKNOWNin every custody mode, and nothing is sent. The mode is still read fresh before every encrypt.crypto.federatedToken({ crypt, op })(POST /crypto/federated-token): a short-lived identity token (RS256 JWT, at most 15 minutes) to present to your own cloud's token exchange for BYOK and HYOK keys. Returns{ token, expiresAt, issuer, subject, audience, kid }(FederatedToken). A crypt that does not match[a-z0-9-]{1,64}or anopother thanencrypt,decryptorrewrapis refused before sending (K9O_INVALID_FIELD_VALUE). 409K9O_CUSTODY_SERVER_ROUTE, 429K9O_RATE_LIMITEDand 503K9O_KEY_SERVICE_UNAVAILABLEare raised as they come and never retried.FederatedTokenandFederatedTokenRequestare exported.expectedKeyRefsclient option: the identifiers of your own KMS or HSM keys, for BYOK and HYOK. The SDK passes the list to the client core as{ expectedKeyRefs }on everyencrypt,decryptandrewrap, and the core refuses a key that is not in it before it uses any token or makes any network call (the key version is ignored). A client built with an empty list, a*or a blank entry is refused withK9O_INVALID_FIELD_VALUE.ClientCryptoCoremethods take the options as a third argument, and a core declares that it enforces the pin withenforcesExpectedKeyRefs: true; with the option set and no declaration the call is refused withK9O_CRYPTO_KEY_PIN_UNENFORCEDbefore the core is called.keyRefMatches(keyRef, expected, provider)compares by the named provider's rule (the provider is required, never inferred from the reference) (AWS whole reference; GCP without the version; Azure the first five parts in lower case; Vault<path>/<key>without:<version>).keyRefMatches,ClientCoreOptionsandKeyRefProviderare exported.k9o.rampart:classify(input, { label }),jwks()andverifyReceipt(result, input, options).classifyreturns the verdict (classification,riskScoreandconfidencein basis points,categories,calibrationVersion),classificationReceiptandprojectIdas received; while the classifier is unavailable it throwsK9O_RAMPART_CLASSIFIER_UNAVAILABLE(503), never a default pass. Rampart is advisory: the caller blocks.verifyReceipttakes the classify result or a bare receipt string and checks the key bykid,algEdDSA,typ, the signature, the issuer (from the key feed, whichjwks()returns as{ keys, issuer }, or theissueroption), the project (the signedproject_idagainst theprojectIdoption or the one the classify result carries), the time window (60 s clock skew) and the SHA-256 of the canonical input, and returns the verified claims or throwsRampartReceiptErrorwith areason(malformed,key_unavailable,key_unknown,alg,typ,signature,issuer,project,project_unknown,expired,not_yet_valid,input_hash). It fetches/rampart/jwksitself unless you passkeys, keeps the keys for the life of the client and refetches once on an unknownkid. The input is canonicalised with the platform's JSON profile (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; send such values as strings.jcsCanonicalizeand SHA-256 are in the package; 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 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.verifyReceiptreturnswindows, the number of windows the receipt says were scored (a receipt without the claim reads as 1; awindowsthat is not a positive integer is refused asmalformed), and ignores claims it does not know.RAMPART_ERROR_CODESandisRampartInputTooLong(e)name the two no-verdict errors.k9o.analytics(datasets):list,query(read-only SQL overdataset.<slug>tables),create,get,delete,materialize,read(cursor pages inmeta.cursor.next),write(an array or newline-delimited JSON, withonError),upload(multipart CSV or JSON, withdryRunand a creatingmanifest) anddownloadOriginal(the stored file as bytes), plusanalytics.rollupsandanalytics.schedules(create,list,delete,reattest).k9o.rollups:list,read(from,to,dims; suppressed cells arrive as{ status: "suppressed", reason: "cohort_below_k" }) andsubscribe(onecellevent per closed cell,payloadbeing the cell withcellKey,bucket,dims,measures,final; a suppressed cell setssuppressed: true; frames are deduped oneventIdand resumed from the frame'sid:, withfromSequenceon the first connection;onResyncis called with actionreread-source). A rollup or schedule pauses once itsreattestIntervalDays(7, 30, 90 or 365) pass without a re-attestation.reattestis for people only: a service, workload or extension token gets 403K9O_RBAC_DENYwithcontext.reasonhuman_only(a personal access token acts as its person).k9o.keys:list(status: "all"adds rotating and revoked versions),getandrotatefor the project's encryption keys. Keys are metadata only (id,version,status,custodyMode,createdAt,rotatedAt,byokRef,hyokRef); no key material. Reading needs the project-admin or project-auditor role;rotate(keyId, { stepUp })needs project admin plus a step-up proof: 401K9O_STEP_UP_REQUIREDcarries the challenge atcontext.stepUp(alsostepUpChallengeOf(error)), and an optionalstepUphook receives it with the HTTP method and URL and returns{ method, proof }; the SDK sendsx-k9o-step-up-proofand retries exactly once (a second 401 is thrown, never looped).listis not paged and returns{ items }.rotatealso answers 409K9O_STATE_CONFLICT(rotation_in_flight,key_not_active) or 429K9O_RATE_LIMITED(rotation_rate_cap: 3 per rolling 24 hours;key_service_busy).k9o.audit.tail(options): follow the project's audit log live (types,signal,onResync,idleTimeoutMs,retryDelayMs). Events are{ auditEventId, type, actorType, occurredAt, outcome, eventId }(outcomeisnullwhen there is none,eventIdis the stream frame's own id); read the full row withaudit.query. The five fields are unwrapped from the gateway'spayload. The stream'sid:andeventIdbelong to the frame, not to the audit event: the reader dedupes oneventIdand resumes withLast-Event-IDset to the frame'sid:. On areplay-ledgerresync it callsonResync, replays the audit log after the lastauditEventIdreceived (pages whilehasMore), yields the catch-up once, and continues live.warden.checkpointis not in the live tail.k9o.audit.replay({ afterAuditEventId | fromSequence })returns one page{ events, nextCursor, hasMore }from the audit log in order; each event is flattened the same way and carries itssequence(a string). After aresyncthe tail now connects fresh first, buffers its frames, replays from the last deliveredauditEventId, then merges replay, buffer and live once each (nothing published in between is lost; two resyncs in a row back off);audit.replaysendslimit: 1000when none is given and refuses a limit below 1 or above 10000 withK9O_INVALID_FIELD_VALUE.k9o.rampart.classifyrefuses aninputthat is not a JSON object before sending, withKErrorK9O_INVALID_FIELD_VALUE(the gateway reads a bare string wrongly).k9o.crypto(server-side encryption):encrypt,decrypt,rewraponPOST /crypto/{encrypt,decrypt,rewrap}with{ crypt, items }, 1 to 100 items, bytes or UTF-8 strings in and out (the SDK does the base64), 64 KiB per item and 1 MiB per call, context up to 256 bytes; limits are checked before sending withK9O_INVALID_FIELD_VALUEandK9O_PAYLOAD_TOO_LARGE. Each batch item carries its own result or code; the item shape follows the gateway. Machine calls (encrypt needs a crypt grant; decrypt and rewrap need a service token created with the crypt, a workload policy that names it, a scoped personal access token created with step-up, or a session with a fresh step-up; extensions, end users and mobile cannot call it; IAM on the crypt decides, default floorPROJECT_EDITOR). The calls route by custody:encryptreads the project's custody mode (crypto.mode(), never cached) on every call and sends plaintext to the platform only for platform-held keys, with the epoch ascustodyEpoch, re-routing once on 409K9O_ZK_STORE_FLOW_REQUIRED; an unknown, missing or malformed mode answer raisesK9O_CRYPTO_CUSTODY_UNKNOWN(no HTTP status;context.custodyModeis the value seen) and a failed mode call rethrows its own error unchanged; neither sends anything.decryptandrewraptry the platform first and open the ciphertext through the client core (crypto.useClientCore(core), filled by the Kibo binding) when the platform answers 409 withcontext.routeclient. With no client core, a BYOK or HYOK project gets 501K9O_ZK_CLIENT_CORE_UNAVAILABLEand nothing is sent. Ciphertext follows the project KEK's lifecycle only (a zeroize or purge makes it unreadable; per-subject erasure does not reach it). It is a different construction from client-side Kibo and fromk9o.kibo.encrypt, with its own AAD domain; none opens another's ciphertext. Give the same crypt and context on decrypt. Never retried after a 5xx. The gateway route is not live yet; a 404 is expected today.- A
Retry-Afterheader on an error answer now setsKError.retryAfterSecwhen the error body gives no wait of its own. Moat(also@k9o/core/moat): a local guard for a model call, with no network access.messages(input)pins your prompt as the onlysystemmessage and refuses input carrying a role or system marker;checkOutput(output)enforces an output schema and an optional PII filter; input and output schemas use a documented JSON Schema subset (other keywords are rejected at construction);promptSha256()hashes the pinned prompt. Refusals areMoatRefusalwithreasonrole_marker,input_schema,output_schemaorpii. The pin is structural: it stops injected text from becoming the system prompt, not from reaching the model. Role markers are matched after NFKC, removal of combining marks, removal of default-ignorable and format characters, mapping of a small set of Cyrillic and Greek look-alikes of the marker letters to the Latin letter (not general homoglyph detection), case-folding and horizontal-whitespace collapsing, and the shared marker vectors run as a test.k9o.metadata: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 takesfromSequence. 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 asKError.k9o.realtime.subscriberesumes by itself: when the stream ends or the network drops it reconnects withLast-Event-ID, drops events it already delivered, and treats a 45 second silence as a dead connection. Events gaineventId. The newonResyncoption is called when the server loses the position (aresyncnotice, no longer silently skipped); the subscription then continues on a fresh connection. A 4xx answer is thrown once; 5xx and network errors are retried. OptionsidleTimeoutMsandretryDelayMstune the timers.streams.subscribeis unchanged.approvals.listtakescursorand pages like the other lists: the next cursor ismeta.cursor.next(nullon the last page; the result is typedPaginatedEnvelope). An invalid cursor is a 400K9O_INVALID_CURSOR(KError).approvals.bulkresults gainfailed, a list of{ id, code, reason }for matched rows that were not decided (empty when none); the HTTP status stays 200, so compareaffectedIdswith what you intended.requireApproval()on single-recordinsert,updateanddelete(k9o.from("orders").insert({...}).requireApproval()): the write is queued for approval (HTTP 202) instead of applied. The result is the queued change (QueuedChange) or, when anauto_approvepolicy applies the write at once, the normal result;isQueuedWrite(result)tells them apart. Upserts and bulk writes do not take it.k9o.functions.triggers:list,create,updateanddeletefor a function's event triggers (collection,events,filter,enabled,logOkInvocations).deleteanswers 204, sodataisundefined. The SDK checksevents(1 to 4 ofinsert,update,delete,upsert) and the collection name before sending.k9o.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.k9o.endUsers:listandgetfor the project's end users, androleGrants.list,grantandrevokefor the roles they hold.roleis any string;roleGrants.listreturns the grants array; revoking an unknown or already revoked grant answers{ revoked: false, revokedAt: null }.k9o.vectors:nearest(collection, { queryVector, topK, minScore, 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). A collection name must start with_. The SDK checks the name, the vector length and numbers,topK,metricand the row count before sending.k9o.custody.status(): the project's key custody (mode,attached,provider,lastJob,hsm). Read-only; needs the project-admin or project-auditor role.- README sections for writes that wait for approval, function triggers, schedules, vector search and end-user role grants.
- README: what an event-trigger function receives (the JSON payload, redaction,
triggeredAt, and deduping oneventId). KError.requestIdis filled from the gateway'sx-k9o-request-idresponse header on every non-2xx answer when the error body carries norequestId; a body value wins.requestIdis the gateway's request id; log it and give it to support.
Changed
- The cursor-paged lists
functions.list,schedules.list,schedules.runs,endUsers.listandschema.collections.listresolve toPaginatedEnvelope, sopage.meta.cursor.nextis typed and needs no cast. This is a type change only; the response is unchanged. - Breaking:
audit.tailis now the live audit feed (an async iterable). It was a one-shot read of the last minutes ({ sinceMinutes, limit }); useaudit.query({ after, limit })for that. vectorSearchon the select builder sends the embedding in the request body (POST data/<collection>/search) instead of the URL, so real embeddings work. It cannot be combined withtextSearch.insert()returns a builder that you canawaitas before (it also hascatchandfinally); chainrequireApproval()to queue the write.
Fixed
realtime.subscribeandmetadata.subscribe(androllups.subscribe) no longer loop on theresyncframe the gateway sends when a connection opens withoutLast-Event-ID. That frame only reports the head of the stream and the events follow on the same connection, so it is now skipped:onResyncis not called and the connection is not closed. Aresyncafter an event was received, or on a connection that sentLast-Event-ID, is still a real resync. Before, such a subscription reconnected for ever and delivered nothing.audit.tailis unchanged.- A gateway error whose
recommendationis an object ({ action }or{ retryAfterSec, note }) now gives the action text (or note) asrecommendation; before, the object was passed through although the type isstring | null. Any other JSON type givesnull. The newretryAfterSecfield holds the wait the gateway asked for, ornull. It does not change retries.
1.4.0 — 2026-10-26
Added
client.ai.generate(prompt, options): generate text from a prompt (model,maxTokens,temperature,usageType). Same result ascompute.llms.invoke.client.streams:create,list,get,delete,publish,replayandsubscribefor a project's data streams.streams.subscribeis an async iterable of events ({ sequence, subject, data, publishedAt }) withclose(). It reopens the connection from the last sequence when the server closes it, and ends onsignalorclose().client.approvals:list,get,approve,rejectandbulkfor the pending-change queue.approvecan answer with a change that is stillpending_approval: the approval was recorded and more approvers are needed.bulkreturns{ attestationId, action, affectedCount, affectedIds, reason }; compareaffectedIdswith what you intended.rejectand bulkrejectneed areason; the SDK checks it.client.approvalPolicies:list,createanddeletefor the rules that queue or auto-approve writes.deletereturns{ id }.client.schema.collections.list({ limit, cursor }): the project's collections with row, column and index counts and the last migration, one cursor page at a time.- README sections for raw SQL (
client.query) and search (client.search,textSearch,vectorSearch), approvals, approval policies and schema collections. K9O_STREAM_UNAVAILABLEandK9O_STREAM_INVALIDreach you asKError, with the gateway's message.- Streaming requests accept an abort
signal.
Changed
- Function deploy examples use the sandbox tier.
1.3.0 — 2026-10-26
The SDK now matches the gateway. It passes the gateway's field names through, so some inputs and results change.
Changed
- Inputs:
projects.createtakesdisplayName.functions.deploytakesartifactKey,versionandtier. - Inputs: policies and
policies.validatetake apolicydocument. - Inputs: audit filters are
eventType,actorId,afterandbefore. - Inputs:
policies.publishtakes an optionalacknowledgeSelfLockout.me.profile.updatetakeslocaleandtimezone. - Inputs:
me.apiTokens.createtakeslabel,scopeManifestandttlSeconds.org.smtp.settakespasswordRef, not a password. - Inputs:
org.auditLog.querytakestypeandlimitonly.migrations.listPendingtakes an optionalstatus. - Inputs:
org.members.listfilters byuserId,role,acceptanceStatus,statusandstate. - Inputs:
functions.listalso filters bytierandsource. - Project results:
displayNamereplacesname.custodyModeisPLATFORM_MANAGED,SKR,BYOKorHYOK. - Project results also carry
region,status,roleandresidencySet. - Policy results: bundles carry
policy,projectIdand astatusofdraft,publishedorsuperseded.validateanswers{ valid: true }. policies.publishanswers{ pendingChangeId, bundleId, status }: the publish waits for approval.policies.deletereturns no data.- Migration results:
applyandapplyPendinganswer{ applied, skipped }withoutappliedAt. Pending rows useid,queuedAtandqueuedBy. - Function results: records add
version,entryPoint,retiredAtanderrorDetail. The failed status iserror. functions.deletereturns the retired record.- Org results:
org.get()and theorgsmethods returndisplayName. Members addinvitedAt,acceptedAtandstate. org.members.inviteanswers{ invitation, delivery }when the email has no account.org.members.removereturns no data.- Org groups carry
sourceand nomemberCount. Org audit events carrycreatedAt.org.smtp.setandorg.smtp.unsetreturn the org. org.smtp.testanswers{ accepted, resolvedTier, to, dryRun }.meresults: profiles addmfaEnabledandupdatedAt. Sessions useissuedAt,expiresAtandisCurrentSession.compute.llms.invokeresults usecontentandusage. Inference parameters are sent flat in the request.- Signed URLs: the gateway signs for 900 seconds at most. The answer's
expiresInis the lifetime it used. - Host handling: the API host comes from the base URL.
orgSlugbuilds<orgSlug>.api.<apex>on any platform host, not only the default one. - The README is rewritten and checked against the source.
Removed
client.metadata.client.realtime.replay, the WebSocket transport and polling.subscribe(server-sent events) remains.org.members.getandorg.smtp.get.org.auditLog.tail. The org audit log cannot filter by time.org.groups.createandorg.groups.delete. Groups come from your identity provider, so onlylistandgetremain.me.notifications,me.auditLogandme.dataExport.
Added
functions.uploadArtifact(bytes, kind)uploads a function's bytes and returns itsartifactKey.- A contract test checks 100 SDK calls against the gateway's published 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.