Go changelog
Release notes for k9o.dev/sdk-go, from the CHANGELOG.md in the sdk-go repository. Read on 17 November 2026 at 15:55 UTC.
1.5.2
Released with k9o.dev/sdk-go/kibo 1.5.2, which adds linux/arm64. All SDKs are at 1.5.2 from this release.
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.1
Released with k9o.dev/sdk-go/kibo 1.5.1, which replaces the unusable kibo 1.5.0.
1.5.0
Changed
Audit.TailandAudit.Replayread the gateway's real frames. The five audit fields sit inside the frame'spayload, and the frame's SSEidis the feed's own id, not the audit event's: the tail now delivers one event per frame (AuditEventID,Type,ActorType,OccurredAt,Outcome, plusEventIDfor the frame), de-duplicates on the frame'seventId, resumes withLast-Event-IDset to the SSEid, and keeps the lastAuditEventIDfor the catch-up. After aresyncthe tail now reconnects first without a position, holds the frames that arrive, replays the log after the last delivered event, then merges replay, held and live frames, eachAuditEventIDonce, so nothing published during the catch-up is lost; repeated resyncs back off.Audit.Replaywith noLimitsendslimit: 1000(up to 10000 when given; outside 1 to 10000 isK9O_INVALID_FIELD_VALUE).Audit.Replayreturns anAuditReplayPage(Events,NextCursor,HasMore) with the events flattened the same way;Sequenceis a string andTopicis added.AfterAuditEventIDwins overFromSequence. Before this change the tail delivered no events and a replay returned an empty list.RollupCellEventcarries the decoded payload of acellframe (CellKey,Bucket,Dims,Final,Measures,Status,Reason,Topic,OccurredAt,Suppressed()), withDatastill holding the payload as received.EventIDis the frame'seventId; the resume cursor is the SSEid. Aresyncwith the actionreread-sourcereachesOnResync.Keys.Rotate(ctx, keyID, KeysRotateOptions{StepUp})takes an optional step-up function. On 401K9O_STEP_UP_REQUIREDthe SDK calls it once with theStepUpRequest(the challenge, the HTTP method and the URL), then sends the same request again with thex-k9o-step-up-proofheader, and never a second time. Without it the 401 comes back with the challenge onKError.StepUp.KErrorgainsStepUp,CauseandUnwrap.KeyListno longer hasNextCursor: the key list is not paged.Rampart.Classifyrefuses aninputthat is not a JSON object (a string, number, list or nil) withK9O_INVALID_FIELD_VALUEbefore sending; the gateway will answer 400 for it.
Added
Approvals.Comments.Add(ctx, pendingID, AddApprovalCommentInput{Body, Visibility})posts a comment on a pending change (POST /@<slug>/pending-approvals/<pendingId>/comments) andApprovals.Comments.List(ctx, pendingID, ListApprovalCommentsOptions{Limit, Cursor})reads the comments the caller may see, oldest first, as anApprovalCommentPage(Comments,NextCursor).VisibilityisApprovalCommentEveryoneorApprovalCommentApproversOnly, fixed when posted.Addchecks the id, a body of 1 to 4000 characters and the visibility before sending (K9O_INVALID_FIELD_VALUE). Needs a session; a personal access token alone is refused with 403K9O_RBAC_DENY. Other refusals:K9O_APPROVAL_COMMENT_NOT_ELIGIBLE(403),K9O_APPROVAL_COMMENT_CLOSED(409),K9O_NOT_FOUND(404).Realtime.Replay(ctx, topic, RealtimeReplayOptions{FromSequence, UntilSequence, Limit, AfterAuditEventID})reads a topic's events in order (POST /@<slug>/realtime/replay) and returns aRealtimeReplayPage(Events,NextCursor,HasMore,Resync).RealtimeEventgainsSequence, set on replayed events.Audit.Replayis unchanged.Gate.SignInasks the project which region holds the email first (POST /@<slug>/gate/locate, body{"email": ...}only, no credential headers, noDefaultHeaders) and sends the password to the origin it names only if that host is your own org, gateway family and apex with the region code added or swapped in (https; no userinfo, port, path, query or fragment; the code equals the answer'sregion). Anything else, a null origin or an unreadable answer uses the client's base URL. The located origin is not cached; a bounded hint (64) per refresh token sendsGate.RefreshTokenandGate.SignOutto the origin that issued the session and is removed on sign-out. A non-2xx answer from that step (K9O_RATE_LIMITED,K9O_GATE_REGION_UNAVAILABLE, ...) is returned as the*KError, the password is not sent, and nothing is retried. If the project's locate step answers 404, the client uses the base address.- The Kibo client core matches the configured key against the call's
ExpectedKeyRefsbefore it requests a federated token or exchanges a credential; a key outside the call's pin getsK9O_CRYPTO_UNEXPECTED_KEYon every item, with no token request and no seal or open. - 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.Modestill sends no query. Crypto.ModeFor(ctx, crypt)asks the custody mode about one crypt (?crypt=<crypt>); a bad crypt is refused withK9O_INVALID_FIELD_VALUEbefore sending.Crypto.Mode(ctx)is unchanged.Crypto.Encryptreads theroutefield of the project's mode answer (CryptoMode.Route). On BYOK or HYOK only an explicit"server"sends plaintext to the platform (it still needs a non-empty epoch); a missing route or"client"uses your client core. A route that is neither"server"nor"client"is refused withK9O_CRYPTO_CUSTODY_UNKNOWNon any custody mode, and nothing is sent. The mode is still read fresh before every encrypt.Crypto.CryptsList,CryptsCreateandCryptsRetiremanage the crypt registry (GET/POST /@<slug>/crypto/crypts,POST .../crypts/<name>/retire) and returnCrypt(Name,Statusactiveorretired,CreatedAt,RetiredAt). A bad name is refused withK9O_INVALID_FIELD_VALUE(fieldname) before sending, andCryptsCreatesends onlyname. An answer with a missing list, an unknown status, a missingnameorcreatedAt, or aretiredAtthat is neither a string nor null isK9O_INTERNAL_ERROR. Gateway refusals (K9O_CRYPT_ALREADY_EXISTS,K9O_CRYPT_LIMIT_EXCEEDED,K9O_CRYPT_RETIRED,K9O_CRYPT_NOT_FOUND,K9O_RBAC_DENY) come back as the*KError. Needscrypto:manage_crypts(project admins by default). A retired name only makesEncryptrefuse it;DecryptandRewrapnever read the registry.CryptoFederatedTokenhas optionalProjectIDandProviderfields, filled when the gateway names them and empty otherwise. A client core checks them against its own configuration and never follows them.Crypto.FederatedToken(ctx, 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,ExpiresAt,Issuer,Subject,Audience,Kid). The crypt andop(encrypt,decrypt,rewrap) are checked before sending; the call is never retried, and the token is never put in an error.ClientOpts.ExpectedKeyRefspins the keys your own KMS or HSM holds (BYOK and HYOK).Cryptopasses the list to the registered client core on every call in a newCryptoCoreOptionsargument, and the core refuses any other key before it uses a token or makes a network call. A core declares that it does by implementingCryptoCoreEnforcer(EnforcesExpectedKeyRefs() bool) and returningtrue; with the option set and no declaration,Encrypt,DecryptandRewrapreturnCryptoCodeKeyPinUnenforced(K9O_CRYPTO_KEY_PIN_UNENFORCED, no HTTP status) before the core is called.NewClientrefuses an empty list, or a blank, spaced or*entry, withK9O_INVALID_FIELD_VALUE.KeyRefMatches(keyRef, expected, provider)compares by the rule of the provider you pass (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>), withKeyRefProviderconstantsKeyRefAWS,KeyRefGCP,KeyRefAzureandKeyRefVault.CryptoClientCore.Encrypt,DecryptandRewraptake theCryptoCoreOptionsas a last parameter.Realtime.Subscriberesumes the change feed on its own: it reconnects withLast-Event-IDwhen a stream ends (the gateway closes one after at most 300 seconds) or the connection drops, drops events it already delivered (byEventID, the last 1024 remembered), ignores heartbeats, and replaces a connection that sends no bytes for 45 seconds. A 4xx answer ends the subscription once; 5xx answers and network errors are retried with a delay of up to 30 seconds.RealtimeEventgainsEventID.SubscribeOptions.OnResyncruns on aresyncframe, which is not delivered as an event, and the subscription continues without a position. Delivery is at-least-once.KError.RequestIDis filled from the gateway'sx-k9o-request-idresponse header when the error body has none (a body value wins; empty when neither is present), on every error built from a non-2xx response, including stream opens, dataset downloads and the key-set fetch.KError.RetryAfterSec(*float64): the wait the gateway asked for, from theretryAfterSecnumber in therecommendationobject; nil when there is none. Retry behavior is unchanged.RequireApproval()on single-record inserts (InsertOne),UpdateandDelete: the write is queued for approval (HTTP 202) instead of applied. The result is the queued change or, when anauto_approvepolicy applies the write at once, the normal result;AsQueuedChangeandIsQueuedWritetell them apart. Upserts and bulk writes do not take it.Functions.Triggers:List,Create,UpdateandDeletefor a function's event triggers (Collection,Events,Filter,Enabled,LogOkInvocations).Deleteanswers 204, so it returns only an error. 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.List,GrantandRevokefor the roles they hold.Roleis any string; revoking an unknown or already revoked grant answersRevoked: false.Vectors:Nearest(ctx, collection, queryVector, NearestOptions{TopK, MinScore, Metric, Filters})andUpsert(ctx, 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.Approvals.ListtakesCursor; the next page's cursor ismeta.Cursor.Next(nil on the last page).Approvals.Bulkresults carryFailed(ID,Code,Reason), an empty list when no row failed; the answer is HTTP 200 even when rows fail.Meta.Approval, set on the answer to a queued write.VectorSearchon the select builder sends the embedding in the request body, so real embeddings work. It cannot be combined withTextSearch.Custody.Status: the project's custody mode, provider, last job and HSM details (read-only).Metadata:Filter,Set,Search,Vectors.Nearest,Subscribe,Index.GetandIndex.Declarefor the columns you declare on a collection. Column names get themetadata.prefix when it is missing. The SDK checks surfaces,LimitandK(1 to 1000), operators,Metric, the embedding, the 64-column limit andCursorwith more than one surface before sending.Nearestreturns no score and at most 50 rows;Searchhas no second page;Subscribeevents carry onlycollectionandid, reconnect withLast-Event-IDand takeFromSequenceon the first connection only.DecodeMetadataChangereads an event's payload.Rampart:Classify,JWKSandVerifyReceiptfor the hosted classifier.Classifyreturns the verdict and the signed receipt as received; Rampart is advisory and blocks nothing, and an unavailable classifier is an error (503K9O_RAMPART_CLASSIFIER_UNAVAILABLE), never a pass.VerifyReceipttakes theClassifyresult (or a bare receipt string) and checks the key (bykid, from the key feed, cached with one refetch on an unknownkid),alg,typ, the Ed25519 signature,iss(theIssueroption, else the issuer the key feed advertises),project_id(theProjectIDoption, else the one on theClassifyresult),iat/exp(60 s skew by default) and the input hash, and returns the verified claims or a*ReceiptError(malformed,key_unknown,key_unavailable,alg,typ,signature,issuer,project,project_unknown,expired,not_yet_valid,input_hash).CanonicalJSONis the platform's canonical form used for the input hash (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. 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:List,Get,Create,Delete,Query,Read,Write,Upload,DownloadOriginalandMaterializefor datasets, andAnalytics.RollupsandAnalytics.Schedules(Create,List,Delete,Reattest).Rollups:List,ReadandSubscribe(closed cells live, on the change feed).Reattestis for people only: a service, workload or extension token gets 403K9O_RBAC_DENY(reasonhuman_only). A rollup or schedule pauses after its 7 to 365 days unless a person re-attests it.Keys:List,GetandRotatefor the project's encryption keys (metadata only, no key material).Rotateneeds project admin and a fresh step-up; 401K9O_STEP_UP_REQUIRED, 409K9O_STATE_CONFLICTand 429K9O_RATE_LIMITED(at most 3 rotations in 24 hours) come back as*KError.Audit.Tail: the project's audit events live (AuditEventID,Type,ActorType,OccurredAt,Outcome) on the change feed, withTypesto narrow it. On areplay-ledgerresync it catches up from the audit log by itself.Audit.Replayreads the log in order after anAuditEventIDor from a sequence.ReceiptClaims.Windows: the number of windows a receipt's input was scored in.CodeRampartInputTooLongandCodeRampartClassifierUnavailablename the two classifier error codes.KError.RetryAfterSecalso reads aRetry-Afterheader given in seconds when the error body carries no wait.moatpackage (k9o.dev/sdk-go/moat): pins the system prompt, validates input and output against a JSON Schema subset, refuses role and system markers in untrusted input, and runs an optional PII filter over output. It runs in your process with no network call and one dependency beyond the standard library (golang.org/x/text, for NFKC). The pin is structural: it stops injected text from becoming the system prompt and does not stop it reaching the model. The marker scan matches on a normalised copy (NFKC, combining marks ignored, ignorable and format characters removed, a small set of Cyrillic and Greek look-alikes of the marker letters read as the Latin letter, case-folded, horizontal whitespace collapsed, matched line by line); the text sent to the model is unchanged.- README sections for Rampart, Moat, writes that wait for approval, function triggers, schedules, vector search, metadata and end-user role grants.
- README: what an event-trigger function receives (the JSON payload, redaction,
triggeredAt, and deduping oneventId). Crypto:Encrypt,DecryptandRewrapfor server-side encryption under the project's key (POST /@<slug>/crypto/encrypt | decrypt | rewrap). The caller never names a key; a requiredcrypt, a registered name ([a-z0-9-]{1,64}, notactions) and an optionalcontextbind the ciphertext, and both must be given again on decrypt. Up to 100 items per call, 64 KiB per plaintext and 1 MiB per call, 256 bytes of context; the SDK checks them before sending (K9O_INVALID_FIELD_VALUE,K9O_PAYLOAD_TOO_LARGE) and does the base64. Each item has its own result or code; the item shape follows the gateway. The ciphertext is opaque and never parsed. A crypto call is never retried. Encrypt can answer 404K9O_CRYPT_NOT_FOUND(name not registered) or 409K9O_CRYPT_RETIRED(name retired; decrypt and rewrap are not refused for either); both pass through as*KError, with constantsCryptoCodeCryptNotFoundandCryptoCodeCryptRetired.Encryptchecks the project's custody mode on every call (Crypto.Mode, no cache) and routes by it: platform-managed, confidential-workload and SKR keys use the server route (the request carriescustodyEpoch); BYOK and HYOK keys use the client route and never send plaintext to the platform. Register a Kibo client core withCrypto.UseClientCore; without one such a call raisesK9O_ZK_CLIENT_CORE_UNAVAILABLE(501). An unknown, missing or malformed mode answer fails closed withCryptoCodeCustodyUnknown(K9O_CRYPTO_CUSTODY_UNKNOWN, no HTTP status) and a failed mode call returns its own error unchanged; neither sends anything.DecryptandRewraptry the platform first and reroute to the client core on a 409K9O_ZK_STORE_FLOW_REQUIREDfor the client route. For machine calls: encrypt needs only a grant on the crypt; 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, and IAM on the crypt decides (default floorPROJECT_EDITOR). The route serves platform-managed keys only: a project whose key is held in the customer's own KMS or HSM (BYOK or HYOK) gets 409K9O_ZK_STORE_FLOW_REQUIREDfor the whole call, pointing to client-sidekibo.encryptandkibo.decrypt, which call the customer's KMS directly (a rewrap into cloud BYOK answers the same 409). The ciphertext is covered by the project key's lifecycle only (a zeroize or a project purge makes it unreadable everywhere), not by per-subject erasure. Client-side Kibo, the extension route and this route are three constructions with different AAD domains, and none opens the others' ciphertext. The route is not live on the gateway yet: a 404 on/crypto/*is expected until it is.
Fixed
Realtime.SubscribeandMetadata.Subscribe(and the other feeds built on the same loop) delivered no events against the gateway. A new connection withoutLast-Event-IDopens with aresyncframe that only reports the current head, and the feed took it for a lost position: it reconnected and calledOnResync, over and over. Aresyncthat is the first data on a connection opened without a position (noLast-Event-ID, noFromSequence) is now informational: no reconnect, noOnResync, and the live events on the same connection are delivered. Aresyncafter an event, or on a connection that sent a position, still callsOnResyncand reconnects without a position.- A gateway error whose
recommendationis an object (for example{"action": "..."}or{"retryAfterSec": 30, "note": "..."}) was reported asK9O_INTERNAL_ERROR. It now keeps its code, message, status and context.Recommendationstays a string: the object'saction, else itsnote, else empty. Any other JSON type in the field also gives an empty string.
1.4.0 — 2026-10-26
Added
QueryandQueryNamed: run one read-only SQL statement with positional or:nameparameters.QueryIntoandQueryNamedIntodecode rows into your own type.Search: full-text search over one column of a collection.TextSearchandVectorSearchon 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.ApprovalPolicies: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.CreatetakesDisplayName(required) and optionalSlug,Region,CustodyMode.GetandUpdateuse the projects routes.Functions.DeploytakesName,Runtime,Tier(gatewayorsandbox),ArtifactKey,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 areEventType,ActorID,After,Before,Limit,Cursor.- Role grants use
/role-grantsand identity providers use/identity-providers, with typed create and update inputs. Org.DefaultLLMGetandDefaultLLMSetreturn records.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.Studio.Workflows.Triggersends{triggerContext}.Gate.SignOutrequires 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.VerifySession,Gate.Hosted,Realtime.Replayand the polling transport.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(ctx, 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.