Skip to main content

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_GATED is no longer documented as an error to expect: the platform no longer gates features by plan.
  • The tierGating option 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_id is filled from the gateway's x-k9o-request-id response header (any case) when the error body carries no requestId; a body value still wins. It was always null for 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 classify on a long input is not cut off.

Added​

  • approvals->comments->add($pendingId, $body, $visibility) and approvals->comments->list($pendingId, $limit, $cursor): comments on a pending change. $body is plain text of 1 to 4000 characters and $visibility is everyone or approvers_only, fixed when posted; arguments are checked before sending (K9O_INVALID_FIELD_VALUE). list returns the comments the caller may see, oldest first, 1 to 200 per page, with meta->cursor->next as the next $cursor. Posting needs a session. Gateway refusals arrive as KError: 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 nextCursor beside data now also reads as meta->cursor->next.
  • realtime->replay($topic, $options): the catch-up read for a realtime topic (POST /@<project>/realtime/replay), one page per call as RealtimeReplayPage (events in the shape subscribe yields, next_cursor, has_more, resync). Options from_sequence, until_sequence, limit (1 to 10000) and after_audit_event_id (audit topics) are checked before sending (K9O_INVALID_FIELD_VALUE). Stored events exist for audit.project.* topics; any other topic answers no events and resync reread-source. audit->replay is unchanged.
  • K9o\FfiAppCore: an AppCore that loads the Kibo core's native library (zk-bundle-v2.16.3 or later) through PHP's FFI extension, for KiboClientCore. It reads and writes the core's byte layout for appCryptoSeal, appCryptoOpen, acquireKmsCredential and coreCapabilities and turns the core's errors into "<CODE>: <detail>". The SDK loads without ext-ffi or the library; the class throws KIBO_WASM_ERROR when used without them. Tested against the real 2.16.3 core: coreCapabilities lists expected_key_refs, and seal calls for AWS, GCP, Azure and Vault with placeholder credentials reach the provider and are refused with UPSTREAM_KMS_ERROR.
  • In a Vault federation for KiboClientCore, the field is jwt_auth_mount (the JWT auth mount: the name Vault serves the JWT login under, jwt for auth/jwt, not the transit mount) and it is required. The adapter hands it to the core as the core's own mount field.
  • gate->sign_in asks 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 is https, 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_token and sign_out go 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 429 K9O_RATE_LIMITED or 503 K9O_GATE_REGION_UNAVAILABLE from that step is thrown as KError, nothing else is sent, and the call is safe to retry.
  • KiboClientCore: a call whose own expectedKeyRefs does not contain the configured key is refused per item with K9O_CRYPTO_UNEXPECTED_KEY before the federated token is fetched and before the cloud exchange.
  • crypto->mode() and crypto->mode($crypt) return the gateway's route ("client" or "server") as CryptoMode::$route, null on older gateways or for an unknown value; follow it, not custodyMode.
  • The custody check before each encrypt names 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), and mode() is unchanged.
  • encrypt follows the route in the project's mode answer. On BYOK or HYOK, only an explicit route server sends plaintext to the server (it needs an epoch); a missing route means your client core. A route that is neither server nor client is refused with K9O_CRYPTO_CUSTODY_UNKNOWN and nothing is sent. The mode is read before every encrypt. crypto->mode() is unchanged.
  • crypto->crypts: the crypt registry. list() returns a list of CryptoCrypt (name, status active or retired, createdAt, retiredAt or null), create($name) registers a crypt (sends only name) and retire($name) retires one (no body). A bad name is refused before sending (K9O_INVALID_FIELD_VALUE, field name); an answer with an unknown status or a missing field throws K9O_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 as KError. Needs crypto:manage_crypts (project admins by default); a personal access token is refused on retire. A retired or unregistered name only makes encrypt refuse it: decrypt and rewrap never 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, decrypt or rewrap), returned as CryptoFederatedToken (token, expiresAt, issuer, subject, audience, kid). crypt and op are checked before sending (K9O_INVALID_FIELD_VALUE); the call is never retried; a response without any of the six fields throws K9O_INTERNAL_ERROR. The token shows as [redacted] in var_dump and print_r.
  • K9o\KiboClientCore: the client core for $client->crypto on a BYOK or HYOK project. It opens and seals on this machine against your own KMS: federated token (fetched on every call), acquireKmsCredential against your cloud, then appCryptoSeal or appCryptoOpen. It runs through an injected K9o\AppCore (appCryptoSeal, appCryptoOpen, acquireKmsCredential, coreCapabilities, arrays mirroring the kibo-kms-rest-ffi types; an implementation of your own satisfies it, or use K9o\FfiAppCore below). expectedKeyRefs is 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 list expected_key_refs in coreCapabilities() or the call throws K9O_CRYPTO_KEY_PIN_UNENFORCED before any token is fetched; a core missing a function throws KIBO_WASM_ERROR. Key, provider, region, role and endpoint come from your configuration only: a token response naming another provider or projectId is refused with K9O_INVALID_FIELD_VALUE and nothing is exchanged. The exchange has a deadline (exchangeDeadlineMs, default 30000) passed to the core as timeout_ms; a core-reported timeout, or one that returns late, is KIBO_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_ERROR is your own KMS); no token or credential appears in a message or a dump.
  • CryptoFederatedToken gains nullable provider and projectId, decoded when the gateway sends them (null otherwise).
  • rampart namespace: classify($input, $label) (advisory verdict, the signed receipt as received, and the project_id the server reports), jwks() (the public receipt key feed: keys and the deployment's issuer) and verify_receipt($receipt, $input, $options). verify_receipt takes a classify result or a bare receipt string and checks the key by kid, EdDSA, typ, the Ed25519 signature, the issuer (from the key feed, or the issuer option), the project (the project_id option, else the one the classify result carries; a bare receipt with neither is refused as project_unknown), the time window (60 s skew) and the input digest, and throws RampartRefusal (a KError) with a reason on 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 needs ext-sodium, now listed in require. A long input is scored in overlapping windows and the highest injection score decides; past 16 windows (about 6,000 tokens) the answer is 413 K9O_RAMPART_INPUT_TOO_LONG with no verdict, and 503 K9O_RAMPART_CLASSIFIER_UNAVAILABLE still means the classifier could not answer. The thresholds (calibration rampart-launch-v1) are a starting calibration and may move; a change is a new calibration_version.
  • rampart: the receipt gains an integer windows claim (windows scored, 1 when the input fits one). verify_receipt returns it as $verdict->windows (null for a receipt without the claim) and ignores any claim it does not know; ClassifyResult carries windows when the response has it. 413 K9O_RAMPART_INPUT_TOO_LONG arrives as a KError, never a verdict.
  • analytics namespace for datasets: list, query, create, get, delete, read, write, upload, download_original and materialize, plus analytics->rollups and analytics->schedules with create, list, delete and reattest. rollups namespace: list, read and subscribe (closed cells over SSE, same reconnecting reader as realtime->subscribe). reattest is for people only: a service, workload or extension token gets 403 K9O_RBAC_DENY (reason: human_only). A rollup or schedule that is not re-attested within its 7 to 365 days pauses.
  • keys namespace: list, get and rotate for the project's encryption keys (metadata only). rotate needs a step-up proof; 401 K9O_STEP_UP_REQUIRED, 409 K9O_STATE_CONFLICT and 429 K9O_RATE_LIMITED (at most 3 per rolling 24 hours) arrive as KError.
  • audit->tail($options): the project's audit log live (auditEventId, type, actorType, occurredAt, outcome, read from the frame's payload, plus the frame's eventId), with types, reconnect by Last-Event-ID (the frame's own id, not the audit event id), duplicate drop and idle timeout. On a replay-ledger resync it catches up through the new audit->replay($topic, $after_audit_event_id, $from_sequence, $limit, $until_sequence), which returns a page (events with sequence, next_cursor, has_more), paging while has_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 (use audit->replay for history); audit->replay sends limit 1000 when none is given and refuses a limit outside 1 to 10000.
  • rollups->subscribe yields the cell in the frame's payload (cellKey, bucket, dims, final, measures) with eventId, and a suppressed flag (status suppressed, reason cohort_below_k); a reread-source resync reaches on_resync.
  • keys->rotate($key_id, ['step_up' => callable]): on a 401 K9O_STEP_UP_REQUIRED the callable gets the StepUpChallenge, the HTTP method and the URL and returns ['method', 'proof']; the SDK repeats the request once with x-k9o-step-up-proof. Without the callable the challenge is on $e->step_up(). keys->list is unpaged and exposes no nextCursor.
  • rampart->classify refuses an input that is not an object with K9O_INVALID_FIELD_VALUE before sending.
  • crypto namespace: encrypt, decrypt and rewrap for 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). encrypt checks the project's custody mode on every call (crypto->mode() returns custodyMode and epoch) and sends the epoch with the request; BYOK and HYOK projects use a client core registered with useClientCore (K9o\CryptoClientCore), or get 501 K9O_ZK_CLIENT_CORE_UNAVAILABLE with nothing sent. decrypt and rewrap try the platform first and reroute to the client core on a 409 K9O_ZK_STORE_FLOW_REQUIRED with route client. The gateway route is not live yet; a 404 is expected today.
  • expected_key_refs client option: a non-empty list of cloud key identifiers (no spaces, no *; otherwise K9O_INVALID_FIELD_VALUE). The crypto router passes it to the registered CryptoClientCore on every encrypt, decrypt and rewrap, as a new trailing array $options = [] parameter (key expectedKeyRefs, 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 new EnforcesExpectedKeyRefs interface; with the option set and no declaration the call throws K9O_CRYPTO_KEY_PIN_UNENFORCED before the core is called. Crypto::keyRefMatches($keyRef, $expected, $provider) compares by the named provider's rule ($provider is required, one of aws, 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>), with Crypto::PROVIDER_* constants. BYOK and HYOK only.
  • KError::$retry_after_sec also reads the Retry-After header when the error body carries no retryAfterSec.
  • 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 are MoatRefusal; 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 needs ext-intl and ext-mbstring (new Moat throws MoatSchemaError without 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.projectId when the server sends it.
  • KError::$retry_after_sec: the retryAfterSec number from an error's recommendation object, or null. It is only a field; retries are unchanged.
  • require_approval() on single-record writes: from($c)->require_approval()->insert($record), and chained on update() and delete(). It sends ?requireApproval=true. QueuedChange::is_queued_write($result) tells a queued change (HTTP 202) from a write an auto_approve policy applied; QueuedChange::from_envelope($result) reads the queued change.
  • functions->triggers: list, create, update and delete for event triggers.
  • schedules namespace: list, get, create, update, delete, runs and run_now.
  • vectors namespace: nearest($collection, $query_vector, ['top_k' => ..., 'min_score' => ..., 'metric' => ..., 'filters' => ...]) and upsert($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, metric and the row count before sending.
  • metadata namespace: filter, set, search, vectors->nearest, subscribe, and index->get / index->declare for the columns you declare on a collection. Column names in where, search and nearest get the metadata. prefix when you leave it out; set writes declared columns only. subscribe uses the same reconnecting reader as realtime->subscribe (events carry the record id only) and takes from_sequence. The SDK checks the surface grammar, limits, cursor rule and the 64-column limit before sending. Gateway codes such as K9O_METADATA_FIELD_NOT_INDEXED, K9O_UNKNOWN_SURFACE and K9O_QUERY_RESULT_TOO_LARGE arrive as KError.
  • end_users namespace: list and get, plus end_users->role_grants with list, grant and revoke.
  • approvals->list($status, $limit, $cursor) pages the queue: pass meta->cursor->next of a page as $cursor of the next (null on the last page).
  • approvals->bulk returns data['failed'], a list of id, code and reason for 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, lastJob and, for an HSM, hsm). Read-only; project admins and auditors.
  • Events from realtime->subscribe carry eventId.
  • $response->meta->approval carries meta.approval.status on a queued write.
  • README: what an event-trigger function receives (the JSON payload, redaction, triggeredAt, and deduping on eventId).

Fixed​

  • realtime->subscribe, metadata->subscribe and rollups->subscribe no longer reconnect forever when a connection opens with a resync frame. A fresh connection (no Last-Event-ID and no from_sequence) opens with an informational resync that carries the live head, and its events follow on the same connection; the opening frame is now skipped without calling on_resync or reconnecting, so events arrive. A resync after an event, on a resumed connection, or on a connection sent with from_sequence is still a lost position: on_resync is called and the next connection starts fresh.
  • realtime->subscribe keeps the change feed going. When a stream ends or fails it reconnects with Last-Event-ID set to the last eventId; 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 by eventId, heartbeat comments are ignored, and a connection silent for 45 seconds is reopened. A resync frame is not yielded: it calls the new on_resync option (['reason' => ..., 'action' => ...]) and the feed continues on a fresh connection without Last-Event-ID. Delivery is at-least-once.
  • vector_search on 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 recommendation is an object (for example {"action": "..."}) no longer escapes as a TypeError. It is thrown as a KError with its code, message, status and context, and recommendation holds the object's action (else note) as text. Any other JSON type in the field gives null.

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 :name placeholders.

  • search($collection, column: ..., q: ...): full-text search over one column, plus text_search and vector_search on select().

  • ai.generate: text generation from a prompt (verb sugar over compute.llms.invoke; model defaults to the org's default LLM).

  • streams namespace for user data streams: create, list, get, delete, publish, replay and subscribe. subscribe tails live events over SSE and reconnects from the last sequence when the server closes the connection.

  • approvals namespace for the pending-change queue: list, get, approve, reject and bulk.

  • approval_policies namespace: list, create and delete.

  • 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->create takes $display_name and an options array (slug, region, custody_mode, ...); projects->get and update use the projects routes.
  • functions->deploy takes name, runtime, tier (gateway or sandbox), artifact_key, version and description. Inline code is gone.
  • functions->invoke sends the payload as {payload}.
  • policies->create, update and validate take a policy document (plus optional rules, editor_mode); policies->list takes only status.
  • audit->query filters are event_type, actor_id, after, before, limit and cursor; unknown keys throw.
  • Org roles, identity providers and default model use the current routes; smtp->set uses password_ref and from_address; smtp->test takes to and subject.
  • me->api_tokens->create takes label and scope_manifest (and ttl_seconds); me->sessions->revoke and revoke_all use new routes.
  • compute->llms->invoke settings are sent flat, and the result has content and usage.
  • studio->workflows->trigger sends the context as triggerContext.
  • gate->sign_out requires 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.io is only the default.

Removed​

  • gate->verify_session, gate->hosted, realtime->replay and realtime->subscribe_poll.
  • me->notifications, me->audit_log and me->data_export.
  • org->groups->create, org->groups->delete, org->members->get and org->smtp->get.

Added​

  • functions->upload_artifact($bytes, $kind) uploads a build and returns the artifactKey for deploy.
  • UrlGrammar::parse_api_host reads 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 an id filter 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.