PHP changelog
Release notes for k9o/sdk, from the CHANGELOG.md in the sdk-php 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
Changed
KError->request_idis filled from the gateway'sx-k9o-request-idresponse header (any case) when the error body carries norequestId; a body value still wins. It was alwaysnullfor gateway errors. This covers the request path, downloads, SSE stream opens, the event connection and the Rampart key feed.- A request may take 120 seconds (was 30) and a connection 10, as in the Python SDK, so a long call such as Rampart
classifyon a long input is not cut off.
Added
approvals->comments->add($pendingId, $body, $visibility)andapprovals->comments->list($pendingId, $limit, $cursor): comments on a pending change.$bodyis plain text of 1 to 4000 characters and$visibilityiseveryoneorapprovers_only, fixed when posted; arguments are checked before sending (K9O_INVALID_FIELD_VALUE).listreturns the comments the caller may see, oldest first, 1 to 200 per page, withmeta->cursor->nextas the next$cursor. Posting needs a session. Gateway refusals arrive asKError:K9O_APPROVAL_COMMENT_NOT_ELIGIBLE,K9O_APPROVAL_COMMENT_CLOSED,K9O_INVALID_FIELD_VALUE,K9O_NOT_FOUND,K9O_RBAC_DENY.- A response that carries its page cursor as
nextCursorbesidedatanow also reads asmeta->cursor->next. realtime->replay($topic, $options): the catch-up read for a realtime topic (POST /@<project>/realtime/replay), one page per call asRealtimeReplayPage(eventsin the shapesubscribeyields,next_cursor,has_more,resync). Optionsfrom_sequence,until_sequence,limit(1 to 10000) andafter_audit_event_id(audit topics) are checked before sending (K9O_INVALID_FIELD_VALUE). Stored events exist foraudit.project.*topics; any other topic answers no events andresyncreread-source.audit->replayis unchanged.K9o\FfiAppCore: anAppCorethat loads the Kibo core's native library (zk-bundle-v2.16.3 or later) through PHP's FFI extension, forKiboClientCore. It reads and writes the core's byte layout forappCryptoSeal,appCryptoOpen,acquireKmsCredentialandcoreCapabilitiesand turns the core's errors into"<CODE>: <detail>". The SDK loads withoutext-ffior the library; the class throwsKIBO_WASM_ERRORwhen used without them. Tested against the real 2.16.3 core:coreCapabilitieslistsexpected_key_refs, and seal calls for AWS, GCP, Azure and Vault with placeholder credentials reach the provider and are refused withUPSTREAM_KMS_ERROR.- In a Vault
federationforKiboClientCore, the field isjwt_auth_mount(the JWT auth mount: the name Vault serves the JWT login under,jwtforauth/jwt, not the transit mount) and it is required. The adapter hands it to the core as the core's ownmountfield. 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 is thrown asKError, nothing else is sent, and the call is safe to retry.KiboClientCore: a call whose ownexpectedKeyRefsdoes not contain the configured key is refused per item withK9O_CRYPTO_UNEXPECTED_KEYbefore the federated token is fetched and before the cloud exchange.crypto->mode()andcrypto->mode($crypt)return the gateway'sroute("client"or"server") asCryptoMode::$route,nullon 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.mode()sends no query. crypto->mode(?string $crypt = null): 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.encryptfollows theroutein the project's mode answer. On BYOK or HYOK, only an explicit routeserversends plaintext to the server (it needs an epoch); a missing route means your client core. A route that is neitherservernorclientis refused withK9O_CRYPTO_CUSTODY_UNKNOWNand nothing is sent. The mode is read before everyencrypt.crypto->mode()is unchanged.crypto->crypts: the crypt registry.list()returns a list ofCryptoCrypt(name,statusactiveorretired,createdAt,retiredAtornull),create($name)registers a crypt (sends onlyname) andretire($name)retires one (no body). A bad name is refused before sending (K9O_INVALID_FIELD_VALUE, fieldname); an answer with an unknown status or a missing field throwsK9O_INTERNAL_ERROR. Gateway refusals (K9O_CRYPT_ALREADY_EXISTS,K9O_CRYPT_LIMIT_EXCEEDED,K9O_CRYPT_RETIRED,K9O_CRYPT_NOT_FOUND,K9O_ACCESS_DENIED,K9O_IAM_POLICY_DENIED,K9O_RBAC_DENY) arrive asKError. Needscrypto:manage_crypts(project admins by default); a personal access token is refused onretire. A retired or unregistered name only makesencryptrefuse it:decryptandrewrapnever read the registry.crypto->federatedToken($crypt, $op): ask for a short-lived RS256 token (valid for at most 15 minutes) for one crypt and one operation (encrypt,decryptorrewrap), returned asCryptoFederatedToken(token,expiresAt,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 throwsK9O_INTERNAL_ERROR. The token shows as[redacted]invar_dumpandprint_r.K9o\KiboClientCore: the client core for$client->cryptoon a BYOK or HYOK project. It opens and seals on this machine against your own KMS: federated token (fetched on every call),acquireKmsCredentialagainst your cloud, thenappCryptoSealorappCryptoOpen. It runs through an injectedK9o\AppCore(appCryptoSeal,appCryptoOpen,acquireKmsCredential,coreCapabilities, arrays mirroring thekibo-kms-rest-ffitypes; an implementation of your own satisfies it, or useK9o\FfiAppCorebelow).expectedKeyRefsis required and non-empty, and the configured key must match it; an empty pin passed per call is refused before any network call. The core must listexpected_key_refsincoreCapabilities()or the call throwsK9O_CRYPTO_KEY_PIN_UNENFORCEDbefore any token is fetched; a core missing a function throwsKIBO_WASM_ERROR. Key, provider, region, role and endpoint come from your configuration only: a token response naming anotherproviderorprojectIdis refused withK9O_INVALID_FIELD_VALUEand nothing is exchanged. The exchange has a deadline (exchangeDeadlineMs, default 30000) passed to the core astimeout_ms; a core-reported timeout, or one that returns late, isKIBO_EXCHANGE_TIMEOUT. The credential is cached per crypt, operation and subject until 60 s before it expires. Item failures carry the core's code (UPSTREAM_KMS_ERRORis your own KMS); no token or credential appears in a message or a dump.CryptoFederatedTokengains nullableproviderandprojectId, decoded when the gateway sends them (nullotherwise).rampartnamespace:classify($input, $label)(advisory verdict, the signed receipt as received, and theproject_idthe server reports),jwks()(the public receipt key feed:keysand the deployment'sissuer) andverify_receipt($receipt, $input, $options).verify_receipttakes aclassifyresult or a bare receipt string and checks the key bykid, EdDSA,typ, the Ed25519 signature, the issuer (from the key feed, or theissueroption), the project (theproject_idoption, else the one theclassifyresult carries; a bare receipt with neither is refused asproject_unknown), the time window (60 s skew) and the input digest, and throwsRampartRefusal(aKError) with areasonon any failure. The input is canonicalised with the platform's 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. It needsext-sodium, now listed inrequire. 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 newcalibration_version.rampart: the receipt gains an integerwindowsclaim (windows scored, 1 when the input fits one).verify_receiptreturns it as$verdict->windows(nullfor a receipt without the claim) and ignores any claim it does not know;ClassifyResultcarrieswindowswhen the response has it. 413K9O_RAMPART_INPUT_TOO_LONGarrives as aKError, never a verdict.analyticsnamespace for datasets:list,query,create,get,delete,read,write,upload,download_originalandmaterialize, plusanalytics->rollupsandanalytics->scheduleswithcreate,list,deleteandreattest.rollupsnamespace:list,readandsubscribe(closed cells over SSE, same reconnecting reader asrealtime->subscribe).reattestis for people only: a service, workload or extension token gets 403K9O_RBAC_DENY(reason: human_only). A rollup or schedule that is not re-attested within its 7 to 365 days pauses.keysnamespace:list,getandrotatefor the project's encryption keys (metadata only).rotateneeds a step-up proof; 401K9O_STEP_UP_REQUIRED, 409K9O_STATE_CONFLICTand 429K9O_RATE_LIMITED(at most 3 per rolling 24 hours) arrive asKError.audit->tail($options): the project's audit log live (auditEventId,type,actorType,occurredAt,outcome, read from the frame'spayload, plus the frame'seventId), withtypes, reconnect byLast-Event-ID(the frame's own id, not the audit event id), duplicate drop and idle timeout. On areplay-ledgerresync it catches up through the newaudit->replay($topic, $after_audit_event_id, $from_sequence, $limit, $until_sequence), which returns a page (eventswithsequence,next_cursor,has_more), paging whilehas_more, and continues. After a resync the tail reconnects fresh first, then replays, then merges (each event once, nothing lost); a new connection starts at the live head and may re-send the last few seconds of events (useaudit->replayfor history);audit->replaysendslimit1000 when none is given and refuses a limit outside 1 to 10000.rollups->subscribeyields the cell in the frame'spayload(cellKey,bucket,dims,final,measures) witheventId, and asuppressedflag (statussuppressed,reasoncohort_below_k); areread-sourceresync reacheson_resync.keys->rotate($key_id, ['step_up' => callable]): on a 401K9O_STEP_UP_REQUIREDthe callable gets theStepUpChallenge, the HTTP method and the URL and returns['method', 'proof']; the SDK repeats the request once withx-k9o-step-up-proof. Without the callable the challenge is on$e->step_up().keys->listis unpaged and exposes nonextCursor.rampart->classifyrefuses aninputthat is not an object withK9O_INVALID_FIELD_VALUEbefore sending.cryptonamespace:encrypt,decryptandrewrapfor server-side encryption under the project's key (batches of up to 100 items, 64 KiB per item, 1 MiB per call, no automatic retry).encryptchecks the project's custody mode on every call (crypto->mode()returnscustodyModeandepoch) and sends the epoch with the request; BYOK and HYOK projects use a client core registered withuseClientCore(K9o\CryptoClientCore), or get 501K9O_ZK_CLIENT_CORE_UNAVAILABLEwith nothing sent.decryptandrewraptry the platform first and reroute to the client core on a 409K9O_ZK_STORE_FLOW_REQUIREDwith routeclient. The gateway route is not live yet; a 404 is expected today.expected_key_refsclient option: a non-empty list of cloud key identifiers (no spaces, no*; otherwiseK9O_INVALID_FIELD_VALUE). Thecryptorouter passes it to the registeredCryptoClientCoreon everyencrypt,decryptandrewrap, as a new trailingarray $options = []parameter (keyexpectedKeyRefs, present only when set); the core must refuse any other key before using a token or making a network call, and declares that it does by implementing the newEnforcesExpectedKeyRefsinterface; with the option set and no declaration the call throwsK9O_CRYPTO_KEY_PIN_UNENFORCEDbefore the core is called.Crypto::keyRefMatches($keyRef, $expected, $provider)compares by the named provider's rule ($provideris required, one ofaws,gcp,azure,vault; nothing is inferred from the reference) (AWS whole reference; GCP without the version; Azure the first five parts in lower case; Vault<path>/<key>without:<version>), withCrypto::PROVIDER_*constants. BYOK and HYOK only.KError::$retry_after_secalso reads theRetry-Afterheader when the error body carries noretryAfterSec.Moat: a local module (no network, no client) that pins the system prompt, refuses role and system markers, checks input and output against a JSON Schema subset, and runs an optional PII filter. Refusals areMoatRefusal;prompt_sha256()hashes the pinned prompt. Marker matching normalises first (NFKC, combining marks ignored, default-ignorable 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, line breaks kept), and it needsext-intlandext-mbstring(new MoatthrowsMoatSchemaErrorwithout them).Jcs::canonicalize(): canonical JSON under the platform's code-point profile (keys sorted by UTF-8 byte order, integers only).$response->meta->project_id:meta.projectIdwhen the server sends it.KError::$retry_after_sec: theretryAfterSecnumber from an error'srecommendationobject, ornull. It is only a field; retries are unchanged.require_approval()on single-record writes:from($c)->require_approval()->insert($record), and chained onupdate()anddelete(). It sends?requireApproval=true.QueuedChange::is_queued_write($result)tells a queued change (HTTP 202) from a write anauto_approvepolicy applied;QueuedChange::from_envelope($result)reads the queued change.functions->triggers:list,create,updateanddeletefor event triggers.schedulesnamespace:list,get,create,update,delete,runsandrun_now.vectorsnamespace:nearest($collection, $query_vector, ['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). A collection name must start with_. The SDK checks the name, the vector length and numbers,top_k,metricand the row count before sending.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 asKError.end_usersnamespace:listandget, plusend_users->role_grantswithlist,grantandrevoke.approvals->list($status, $limit, $cursor)pages the queue: passmeta->cursor->nextof a page as$cursorof the next (null on the last page).approvals->bulkreturnsdata['failed'], a list ofid,codeandreasonfor rows it could not decide (empty when none). The call is HTTP 200 even when rows fail.custody->status(): the project's key custody (mode,attached,provider,lastJoband, for an HSM,hsm). Read-only; project admins and auditors.- Events from
realtime->subscribecarryeventId. $response->meta->approvalcarriesmeta.approval.statuson a queued write.- README: what an event-trigger function receives (the JSON payload, redaction,
triggeredAt, and deduping oneventId).
Fixed
realtime->subscribe,metadata->subscribeandrollups->subscribeno longer reconnect forever when a connection opens with aresyncframe. A fresh connection (noLast-Event-IDand nofrom_sequence) opens with an informationalresyncthat carries the live head, and its events follow on the same connection; the opening frame is now skipped without callingon_resyncor reconnecting, so events arrive. Aresyncafter an event, on a resumed connection, or on a connection sent withfrom_sequenceis still a lost position:on_resyncis called and the next connection starts fresh.realtime->subscribekeeps the change feed going. When a stream ends or fails it reconnects withLast-Event-IDset to the lasteventId; a 4xx answer is thrown once and a 5xx answer or network failure is retried with a growing delay (at most 30 seconds). Events resent on reconnect are dropped byeventId, heartbeat comments are ignored, and a connection silent for 45 seconds is reopened. Aresyncframe is not yielded: it calls the newon_resyncoption (['reason' => ..., 'action' => ...]) and the feed continues on a fresh connection withoutLast-Event-ID. Delivery is at-least-once.vector_searchon the select builder sends the embedding in the request body, so real embeddings work; a long embedding in the URL was refused.- An error whose
recommendationis an object (for example{"action": "..."}) no longer escapes as aTypeError. It is thrown as aKErrorwith its code, message, status and context, andrecommendationholds the object'saction(elsenote) as text. Any other JSON type in the field givesnull.
1.4.0 — 2026-10-26
Added
-
query($sql, $params): one read-only SQL statement; a list binds$1, $2, ..., an array with string keys 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->createtakes$display_nameand an options array (slug,region,custody_mode, ...);projects->getandupdateuse the projects routes.functions->deploytakesname,runtime,tier(gatewayorsandbox),artifact_key,versionanddescription. Inline code is gone.functions->invokesends the payload as{payload}.policies->create,updateandvalidatetake apolicydocument (plus optionalrules,editor_mode);policies->listtakes onlystatus.audit->queryfilters areevent_type,actor_id,after,before,limitandcursor; unknown keys throw.- Org roles, identity providers and default model use the current routes;
smtp->setusespassword_refandfrom_address;smtp->testtakestoandsubject. me->api_tokens->createtakeslabelandscope_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.
- Fixed: boolean filter values are sent as
true/false.eq('done', false)previously sent an empty string. - 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.
Requirements
- PHP 8.5.12 or later.