@theokit/sdk-memory 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,138 @@
 # Changelog — @theokit/sdk-memory
 
+## 0.3.3
+
+### Patch Changes
+
+- 1a4bbcf: The declared `@theokit/sdk` peer ranges stop promising versions the packages do not compile against.
+
+  All three declared `>=4.0.0`. `4.0.1` is the lowest published version that range admits — what a
+  consumer pinning conservatively, or resolving under an older transitive constraint, lands on. npm
+  resolves the combination with no `ERESOLVE` and no peer warning, and the build then fails on
+  `TS2552: Cannot find name` and `TS2305: has no exported member`.
+
+  The floors were measured by bisecting the 116 stable 4.x releases with a real build as the oracle.
+  Each one has its immediately preceding version failing, so these are exact versions rather than
+  intervals:
+
+  | package                | floor      | evidence                        |
+  | ---------------------- | ---------- | ------------------------------- |
+  | `@theokit/sdk-budget`  | `>=4.54.0` | `4.53.1` fails, `4.54.0` passes |
+  | `@theokit/sdk-handoff` | `>=4.54.0` | `4.53.1` fails, `4.54.0` passes |
+  | `@theokit/sdk-memory`  | `>=4.53.1` | `4.53.0` fails, `4.53.1` passes |
+
+  `sdk-memory` sits one release below the other two: this is not one shared migration, it is three
+  packages that each drifted past their own declared floor.
+
+  The oracle deletes every `dist/` before building. Without that the build reads a sibling's output
+  compiled against a different version, which is how a package "passes" against an SDK missing its
+  symbols — the failure mode that made the earlier measurement disagree with CI
+  (usetheokit/theokit-sdk#423).
+
+- 4b5e468: Raises the `@theokit/sdk` peer floor from `>=4.53.1` to `>=4.54.0`.
+
+  Not because this package outgrew 4.53.1 — because **4.53.1's own published declarations do not
+  compile**. Building against it fails inside the SDK's `.d.ts`, not in any code here:
+
+  ```
+  @theokit/sdk/dist/index.d.ts(350,24):  error TS2552: Cannot find name 'AgentBuilderDeps'
+  @theokit/sdk/dist/index.d.ts(3004,15): error TS2304: Cannot find name 'DECLARED'
+  ```
+
+  #345 (`e368fc18`) bound the re-exported names the rollup had left unimported, and first shipped in
+  4.54.0. A floor that names 4.53.1 therefore promises a version nobody can build against.
+
+  Worth separating from the sibling fixes in this release: those floors were wrong because the code
+  had outgrown them. This one is wrong because the version it names is broken — a distinct reason to
+  audit a floor, now recorded beside it.
+
+## 0.3.2
+
+### Patch Changes
+
+- e3f2a82: Public-API documentation reviewed file by file, and corrected wherever it disagreed
+  with the code. The docblocks ship in the `.d.ts`, so these read as behaviour changes
+  in an editor even though no behaviour changed.
+
+  The corrections that change what a caller would do:
+
+  - **`sdk-cache` documented its own premise backwards.** The header example labelled a
+    semantic hit as if it avoided the provider call. `asPlugin()` returns the cached
+    answer as `recalledContext`, which the agent loop injects as a `<memory-context>`
+    block _before_ the prompt — the request still goes to the provider. The two modes
+    are now labelled separately, with a table saying which one short-circuits and which
+    one seeds.
+  - **`sdk-handoff`'s five error classes said "throw".** Under the plugin wiring the
+    handler never throws; every failure becomes a tool result `{"ok":false,…}` handed
+    back to the model. Each class now says where it is actually observable. The header
+    also told readers to `import { Handoff } from "@theokit/sdk"`, from which it was
+    extracted.
+  - **`sdk-budget`'s `charge()` claimed idempotency across concurrent calls.** The mutex
+    serialises, it does not deduplicate: two identical calls record twice. Related, and
+    newly documented: with `maxUsd` set, a model missing from the pricing table denies
+    every request rather than passing it — and the table matches by exact string, so
+    `"openai/gpt-4o"` does not match `"gpt-4o"`.
+  - **The three `memory-*` adapters advertised an env-var fallback they do not read**,
+    and their peer dependencies are required rather than optional. Their behavioural
+    differences are now stated where they break the "interchangeable adapter"
+    assumption — honcho ignores `k` and always throws on `delete`; mem0 recalls across
+    sessions by design; supermemory ignores `sessionId` entirely.
+  - **`sdk-memory`'s `truncated` flag was documented as its own inverse**, and its
+    dreaming sweep claimed a mutex it never takes against the writer it names.
+  - **`sdk-tools`** corrected `run_vitest`'s unreachable `no_vitest` code, `truncation`'s
+    replacement-character claim, and two return shapes missing a live error code.
+  - **`acp`/`cli`** corrected sixteen statements including a named error class that is
+    not the one raised, a handler documented as calling `fork()` that refuses
+    unconditionally, handlers described as pure that mint ids and mutate a store, a
+    config loader credited to Zod in a package that does not import it, and a `--force`
+    scaffold described as atomic that deletes the destination before the rename.
+
+  Undocumented public symbols were documented across every package, with each claim
+  checked against the implementation rather than inferred from the name.
+
+- e368fc1: Every published declaration file now compiles without `skipLibCheck` (#345). The
+  DTS rollup emitted symbols as a re-export from a chunk while omitting them from
+  that chunk's `import`, and dropped type-only imports from external packages —
+  leaving 51 unresolved references across ten of the twelve packages. Nothing broke
+  at runtime, and `tsc` stayed green for anyone with `skipLibCheck` on, but a
+  consumer running type-aware lint saw every type reached through one degrade to
+  `error`.
+
+  The declarations are repaired at build time from the compiler's own diagnostics.
+  No source or API change.
+
+- e699569: **The repository moved to the official `usetheokit` organization.** Every `repository`, `bugs` and `homepage` field now points there, along with the README, `CONTRIBUTING.md`, `SECURITY.md` and the issue templates. Existing clones and any URL already published keep working — GitHub redirects a transferred repository permanently — so this is a correctness fix for the metadata npm renders, not a break.
+
+  **The Apache-2.0 text every package ships was replaced with the official one.** The copy distributed until now had paragraph 4(d) truncated: it read "except as required for describing the origin of the Work and reproducing the content of the NOTICE file", dropping "reasonable and customary use" from the licensed clause. §4(d) governs what a redistributor must do with attribution notices, and the omission narrowed it.
+
+  That matters more than a typo would. The manifests declare the SPDX identifier `Apache-2.0`, which is an assertion that the terms are _the_ Apache-2.0 terms — a licence scanner resolves the identifier and never reads the file. A consumer's compliance review, which does read the file, would find a body that no longer matches the identifier and has no name of its own. Every `LICENSE` in this repository is now byte-identical to the canonical text, with the appendix filled in.
+
+  Nothing else about the terms changed: the licence is the same licence it has always been meant to be, and no package changes what it grants.
+
+- c7385d2: Test runs no longer claim every core on the host.
+
+  None of the package configs capped `maxWorkers`, so vitest's default applied: `os.availableParallelism()`,
+  one fork per core, each booting a full test environment. The repo's `test` script is
+  `turbo run test --filter='./packages/*'`, so that default is paid once per package _concurrently_ —
+  nproc forks times turbo's concurrency, on nproc cores. Measured on a 12-thread machine during an
+  unrelated investigation, two vitest pools alone were enough to reach load average 33.89 with the
+  desktop unusable; a full fan-out is several times that.
+
+  `@theokit/sdk` is the interesting case. B-104 recorded on 2026-08-19 that the `poolOptions.forks.*`
+  block was 100% dead in Vitest 4, deleted it, and noted that `fileParallelism: false` was forcing
+  `maxWorkers` to 1 unconditionally, so a fork-count knob could not act. B-059 then flipped
+  `fileParallelism` to `true` on 2026-08-20, which made the knob able to act again — and nothing
+  reintroduced one, so the package silently went back to the uncapped default. That comment has been
+  corrected along with the config; it claimed no knob existed, which is no longer true.
+
+  The cap leaves 4 cores free (`Math.max(2, cpus().length - 4)`), scaling with the runner rather than
+  hard-coding one machine's core count. It costs no wall-clock: measured in `theokit-ui`, the full
+  suite ran 73.96s at 4 workers against 74.36s at 12, so the parallelism above the cap was already
+  noise. Verified as resolved config rather than as file contents — `createVitest` reports
+  `maxWorkers: 8` on a 12-thread host, which is the formula, not the default.
+
+  This changes no published behaviour; it is test tooling only. Refs usetheokit/theokit-ui#51.
+
 ## 0.3.1
 
 ### Patch Changes

package/LICENSE

@@ -137,8 +137,8 @@
 
    6. Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
 
    7. Disclaimer of Warranty. Unless required by applicable law or
       agreed to in writing, Licensor provides the Work (and each

package/README.md

@@ -4,6 +4,35 @@ Memory subsystem for [`@theokit/sdk`](https://www.npmjs.com/package/@theokit/sdk
 Implements the kernel-facing `MemoryProvider` port (SDK 2.0 Phase 1 / T1.1 —
 Hexagonal Architecture / SOLID Dependency Inversion).
 
+## Install
+
+```bash
+pnpm add @theokit/sdk-memory
+```
+
+`@theokit/sdk` (>=4.0.0) is a peer dependency. Three more are OPTIONAL, and which you need depends
+on the backend you ask for — the in-memory markdown provider needs none of them:
+
+```bash
+pnpm add better-sqlite3      # only when your Node has no built-in `node:sqlite`
+pnpm add sqlite-vec          # vector recall; without it, search is text-only
+pnpm add @lancedb/lancedb    # `backend: "lance"`, for large corpora
+```
+
+The three behave differently when absent, and the difference is worth knowing before you debug a
+thin answer:
+
+- **`better-sqlite3`** — the driver is chosen at runtime. `node:sqlite` is used where the running
+  Node exposes it (22.5+), and this package is the fallback. Opening fails only on a Node without
+  the built-in AND without this installed.
+- **`sqlite-vec`** — the index opens without it and reports `backend: "fts-only"`. Search still
+  works, by TEXT only; no vector table is created. This is a silent degradation by design, so check
+  `index.status().backend` when recall seems shallow.
+- **`@lancedb/lancedb`** — asking for `backend: "lance"` without it raises
+  `ConfigurationError({ code: "lance_backend_unavailable" })` at open time, naming the install
+  command. No silent fallback, because a large-corpus backend quietly becoming a small one is worse
+  than a refusal.
+
 ```ts
 import { Agent } from "@theokit/sdk";
 import { createInMemoryMarkdownProvider } from "@theokit/sdk-memory";
@@ -81,6 +110,19 @@ hook points (init / buildTools / runActivePass / dispose). Your impl
 fulfills the contract; sdk-core never imports this package directly —
 that's the seam that makes the split possible.
 
+## API reference
+
+Every symbol this package exports, with the exact specifier to import it from, is in the generated
+capability map that ships inside `@theokit/sdk`:
+
+```
+node_modules/@theokit/sdk/docs/harness-capability-map.md   # symbol -> import specifier
+node_modules/@theokit/sdk/docs/error-codes.md              # every `code` an error can carry
+```
+
+Both are generated from the built type declarations, so they describe the version you installed
+rather than the version someone wrote a page about.
+
 ## License
 
 Apache-2.0 © useTheo