[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_585":586,"_587":588},"routes/_app.x.$handle.$name",{"_98":97,"_32":45,"_106":88,"_27":107,"_13":14,"_108":-5,"_11":109,"_110":111,"_112":113,"_114":115,"_116":117,"_20":-5,"_118":-5,"_119":-5,"_120":25,"_121":122,"_123":25,"_124":-5,"_125":-5,"_126":127},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_43":44,"_32":45,"_38":46,"_47":-5,"_48":25,"_49":50,"_51":50,"_52":53,"_54":-5,"_18":55,"_56":-5,"_57":25,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":65,"_66":67,"_68":69,"_70":-5,"_71":72,"_73":72,"_74":75,"_76":75,"_77":75,"_78":72,"_79":72,"_80":81,"_82":83,"_84":85,"_86":25},"version",225,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":33,"_34":20,"_35":37,"_38":39,"_40":14,"_41":42,"_24":25},"previous",{"_30":31,"_32":33,"_34":20,"_35":36},"deleted",false,"deletedHere","path","docs/issues/townstash-v1/PRD.md","latestPath","fileId","3faf0a40-7dba-11f1-a5bc-1607ee4eb77e","name","PRD.md","fileType","content","# Spec: Townstash\n\n## Problem Statement\n\nVal Town provides val-scoped SQLite and Blob storage, but neither offers the\nergonomic data-structure API, atomic counters, conditional writes, expiration\nbehavior, and familiar key operations associated with Redis.\n\nDevelopers who need caching, idempotency, rate limiting, counters, queues, or\nsmall shared data structures must repeatedly design storage schemas and\nconcurrency behavior themselves. A reusable Redis-inspired TypeScript library\nwould provide consistent semantics for these use cases without requiring an\nexternal Redis service.\n\nThe library must be honest about its scope. It is a persistent library backed by\nVal Town storage, not an in-memory Redis server, a RESP-compatible endpoint, or\na complete reimplementation of Redis performance and distributed-system\nbehavior.\n\n## Solution\n\nProvide **Townstash**, a Val Town library val that exports a Redis-inspired\nTypeScript API backed by val-scoped SQLite. Consumers import the library from\n`townstash` and interact with its canonical exported client, `stash`. The first\nversion will implement Redis-style string values, key expiration, conditional\nwrites, deletion, existence checks, atomic integer counters, JSON convenience\nmethods, and optional key-prefix helpers.\n\nValues at the core storage boundary are binary-safe sequences of bytes. Text and\nJSON APIs are conveniences layered over that representation. Numbers are not a\nseparate value type: integer operations interpret the current string value as an\ninteger, following the Redis model.\n\nThe library will preserve correctness under concurrent requests by expressing\natomic operations as atomic database operations. Expired keys will be treated as\nabsent during every command that observes key existence, regardless of whether\nbackground cleanup has run.\n\nFuture releases may add hashes, sets, sorted sets, lists, and streams as\nfirst-class value types. These types will not be simulated by silently storing\nmutable JSON documents under string keys.\n\n## User Stories\n\n1. As a Val author, I want to store and retrieve text values by key, so that I\n can persist simple application state.\n2. As a Val author, I want to store and retrieve arbitrary bytes, so that string\n values are binary-safe rather than limited to UTF-8 text.\n3. As a TypeScript developer, I want explicit text, byte, and JSON helpers, so\n that serialization behavior is predictable.\n4. As a Val author, I want missing and expired keys to produce the same\n observable result, so that expiration does not leak storage-cleanup details.\n5. As a Val author, I want to set a key only when it is absent, so that I can\n implement locks, idempotency claims, and first-writer-wins behavior.\n6. As a Val author, I want to set a key only when it is present, so that I can\n avoid accidentally creating state during an update.\n7. As a Val author, I want conditional writes to be atomic, so that concurrent\n requests cannot both succeed when only one should.\n8. As a Val author, I want to attach a time to live when setting a value, so\n that cache and coordination records expire automatically.\n9. As a Val author, I want to add, replace, inspect, and remove a key's\n expiration, so that lifecycle management is available independently of value\n updates.\n10. As a Val author, I want expiration checks to be correct even if no cleanup\n job has run, so that stale values never become visible.\n11. As a Val author, I want to delete one or more keys and learn how many\n existed, so that deletion has useful Redis-like return semantics.\n12. As a Val author, I want to check whether a key exists without retrieving its\n value, so that intent is clear and serialization work is avoided.\n13. As a Val author, I want to increment or decrement an integer value\n atomically, so that counters and rate limits remain correct under\n concurrency.\n14. As a Val author, I want increment and decrement methods to accept an\n optional signed integer amount, so that the API remains expressive and\n Redis-consistent.\n15. As a Val author, I want separate increment and decrement methods, so that\n the direction of a counter change is discoverable and readable.\n16. As a Val author, I want a missing counter to behave as zero before an\n increment or decrement, so that counters need no initialization request.\n17. As a Val author, I want numeric commands to reject non-integer string values\n without changing them, so that invalid counter state is not silently\n corrupted.\n18. As a Val author, I want keys to occupy one flat keyspace, so that the\n storage model matches Redis key semantics.\n19. As a Val author, I want an optional prefixing wrapper, so that I can\n organize application keys without introducing first-class namespace\n behavior.\n20. As a Val author, I want prefixing to be transparent and compositional, so\n that commands operate on the same underlying flat keyspace.\n21. As a Val author, I want to inspect a key's type, so that type errors can be\n diagnosed as additional first-class data types are introduced.\n22. As a Val author, I want commands applied to the wrong value type to fail\n consistently, so that data-model mistakes are visible.\n23. As a library maintainer, I want expired rows to be removable independently\n of command correctness, so that storage can be reclaimed without making\n cleanup timing part of the API contract.\n24. As a library maintainer, I want schema initialization to be idempotent, so\n that importing or initializing the library repeatedly is safe.\n25. As a library maintainer, I want atomic behavior tested against the real\n SQLite adapter, so that tests detect behavior that mocks cannot represent.\n26. As a library adopter, I want documented deviations from Redis, so that I do\n not assume unsupported server, networking, blocking, or performance\n semantics.\n27. As a future library user, I want hashes, sets, sorted sets, lists, and\n streams to have first-class commands and storage behavior, so that\n collections do not require unsafe read-modify-write cycles over JSON\n strings.\n28. As a Val author, I want to import `stash` from the `townstash` library val,\n so that setup is minimal and the API reads naturally at call sites.\n\n## Implementation Decisions\n\nThe durable architectural choices behind this implementation are recorded in:\n\n- [ADR-0001: Use val-scoped SQLite as the storage backend](../../adr/0001-use-val-scoped-sqlite.md)\n- [ADR-0002: Use a flat keyspace of binary-safe string values](../../adr/0002-flat-binary-safe-keyspace.md)\n- [ADR-0003: Determine command results atomically at execution time](../../adr/0003-command-correctness-at-execution-time.md)\n\n- The storage backend is val-scoped SQLite. Blob storage is not the primary\n backend because its documented interface does not provide the\n conditional-write, transactional, and atomic-update primitives required for\n Redis-like command semantics.\n- The product and library val are named **Townstash** and `townstash`,\n respectively.\n- The canonical public export is a ready-to-use client named `stash`.\n- Townstash is distributed as a Val Town library val rather than an npm, JSR, or\n standalone server package.\n- Account-global SQLite is not used by default. Each library instance operates\n within the SQLite database scoped to its val.\n- `stash` exposes a direct TypeScript API using familiar Redis-style command\n names where their semantics can be represented honestly. It does not implement\n the Redis Serialization Protocol or accept connections from existing Redis\n clients.\n- The keyspace is flat. A key contains its complete application-visible\n identifier, including any conventional prefix such as `cache:` or `session:`.\n- Namespace is not a persisted, first-class dimension of key identity.\n- An optional prefixing wrapper may prepend a configured string to every key\n passed through it. This is ergonomic sugar over the flat keyspace, not\n isolation or authorization.\n- The core first-version value type is the Redis string: a binary-safe byte\n sequence.\n- Text access is an explicit decoding convenience over byte values.\n- JSON access is an explicit serialization convenience over string values. JSON\n is not a first-class value type and does not provide path-level reads or\n mutations.\n- Integer counters are stored using string-compatible semantics rather than a\n separate public numeric type.\n- The public counter API provides both increment and decrement operations. Both\n accept an optional signed integer amount. Decrement is semantically equivalent\n to incrementing by the negated amount, so decrementing by a negative amount\n increments the value.\n- Numeric operations are atomic, treat a missing key as zero, and fail without\n mutation when the existing value is not a valid integer.\n- Conditional set behavior supports only-if-absent and only-if-present modes.\n Mutually incompatible options are rejected before execution.\n- Only-if-absent treats an expired key as absent. Only-if-present treats an\n expired key as absent.\n- Expiration is represented as an absolute instant. Public APIs may accept\n relative durations, but commands compare against a consistent current time\n when determining visibility.\n- Expiration is lazy for correctness: every relevant command excludes or\n replaces expired keys as appropriate.\n- Background or explicitly invoked cleanup is a storage-reclamation optimization\n only. Correctness never depends on its schedule.\n- Commands that combine existence checks and mutations must execute atomically.\n They must not use an application-level read followed by a separate write.\n- Multi-statement commands use the database's transactional batch capability\n when a single statement cannot express the required behavior.\n- Schema initialization is safe to run repeatedly and preserves v1 data. V1 does\n not expose a versioned migration path; future schema changes require an\n explicit migration design before they are supported.\n- The first version includes string get/set operations, byte and JSON\n conveniences, deletion, existence, expiration management, type inspection,\n conditional set, and integer increment/decrement.\n- Future first-class types are hashes, sets, sorted sets, lists, then streams.\n Each type receives dedicated data modeling and atomic commands rather than\n being encoded as a mutable JSON string.\n- Streams, if added, initially support persistent append and non-blocking reads.\n Blocking reads and consumer-group coordination require separate design work.\n- Redis compatibility is behavioral and selective. Command names and return\n conventions should remain familiar where doing so does not misrepresent the\n backend.\n\n## API and Data-Model Sketches\n\nThe following stubs capture decisions made during design. They are illustrative\nrather than final implementation prescriptions; names and return types may be\nrefined while preserving the documented behavior.\n\n### Intended usage\n\n```ts\nimport { stash } from \"townstash\";\n\nawait stash.set(\"user:123\", \"Alice\");\nawait stash.get(\"user:123\");\nawait stash.incr(\"views\");\nawait stash.del(\"user:123\");\n\nconst sessions = stash.withPrefix(\"session:\");\nawait sessions.set(\"abc\", \"payload\", { ttlMs: 60_000 });\nawait sessions.get(\"abc\");\n```\n\n`withPrefix` changes only how keys are presented to the underlying flat\nkeyspace. In the example, `sessions.get(\"abc\")` reads the stored key\n`session:abc`.\n\n`setJSON` stores `JSON.stringify(value)` as a UTF-8 string value, and rejects a\ntop-level value that serializes to `undefined`. `getJSON` parses the stored\nUTF-8 text and raises a `SyntaxError` when the value is not valid JSON. JSON\nhelpers do not add path-level reads or mutations.\n\nPrefix wrappers compose in call order: `stash.withPrefix(\"a:\").withPrefix(\"b:\")`\noperates on the flat key `a:b:`. A prefix is not persisted as a namespace\nor security boundary; the complete prefixed key remains directly addressable\nthrough an unprefixed client.\n\n### First-version client surface\n\n```ts\ntype StashValue = string | Uint8Array;\n\ninterface SetOptions {\n /** Expire the key this many milliseconds after command execution begins. */\n ttlMs?: number;\n\n /** Expire the key at this absolute instant. */\n expiresAt?: Date;\n\n /** Set only when the key is absent or expired. */\n nx?: boolean;\n\n /** Set only when the key exists and has not expired. */\n xx?: boolean;\n\n /** Preserve the current expiration when replacing an existing value. */\n keepTtl?: boolean;\n}\n\ninterface Stash {\n get(key: string): Promise;\n getBytes(key: string): Promise;\n\n set(\n key: string,\n value: StashValue,\n options?: SetOptions,\n ): Promise;\n\n setBytes(\n key: string,\n value: Uint8Array,\n options?: SetOptions,\n ): Promise;\n\n getJSON(key: string): Promise;\n setJSON(key: string, value: T, options?: SetOptions): Promise;\n\n del(...keys: string[]): Promise;\n exists(key: string): Promise;\n type(key: string): Promise<\"string\" | \"none\">;\n\n expire(key: string, ttlMs: number): Promise;\n expireAt(key: string, expiresAt: Date): Promise;\n persist(key: string): Promise;\n ttl(key: string): Promise;\n cleanup(): Promise;\n\n incr(key: string, by?: number): Promise;\n decr(key: string, by?: number): Promise;\n\n withPrefix(prefix: string): Stash;\n}\n\nexport const stash: Stash;\n```\n\nThe provisional `boolean` result for `set` means whether the write occurred. An\nunconditional valid set returns `true`; an unsatisfied `nx` or `xx` condition\nreturns `false`.\n\n`ttl` returns remaining milliseconds for a visible expiring key, `-1` for a\nvisible persistent key, and `undefined` for a missing or expired key. `cleanup`\nreturns the number of expired storage rows reclaimed; it does not change the\nvisibility rules used by ordinary commands.\n\n### Counter relationship\n\nBoth public counter methods share one atomic signed-increment primitive:\n\n```ts\nasync function decr(key: string, by = 1): Promise {\n return incrementBy(key, -by);\n}\n```\n\nSigned amounts remain valid. Consequently, decrementing by a negative amount\nincrements the stored value.\n\n### First-version key schema\n\nThe schema keeps one flat keyspace and reserves a type discriminator for future\nfirst-class data structures:\n\n```sql\nCREATE TABLE IF NOT EXISTS stash_keys (\n key TEXT PRIMARY KEY,\n type TEXT NOT NULL,\n value BLOB,\n expires_at INTEGER,\n version INTEGER NOT NULL DEFAULT 1\n);\n\nCREATE INDEX IF NOT EXISTS stash_keys_expiration\n ON stash_keys(expires_at)\n WHERE expires_at IS NOT NULL;\n```\n\n`expires_at` is an absolute Unix timestamp in milliseconds. `version` is\nreserved for mutation tracking and potential future compare-and-swap behavior;\nit need not be exposed in the first public API.\n\n### Lazy expiration\n\nReads treat expired records exactly like missing records:\n\n```sql\nSELECT type, value\nFROM stash_keys\nWHERE key = ?\n AND (expires_at IS NULL OR expires_at > ?);\n```\n\nCleanup exists only to reclaim storage:\n\n```sql\nDELETE FROM stash_keys\nWHERE expires_at IS NOT NULL\n AND expires_at <= ?;\n```\n\nEvery command whose behavior depends on existence must apply the same logical\nexpiration rule. In particular, `nx` may replace an expired row, while `xx`,\n`exists`, `type`, `expire`, `persist`, and `ttl` treat it as absent.\n\n### Atomic increment shape\n\nThe implementation should perform parsing, validation, arithmetic, overflow\nchecking, and mutation as one database operation. It must not read the value\ninto TypeScript and issue a separate write. The earlier design used the\nfollowing upsert shape as a starting point:\n\n```sql\nINSERT INTO stash_keys (key, type, value, expires_at)\nVALUES (?, 'string', ?, NULL)\nON CONFLICT(key) DO UPDATE SET\n value = CAST(stash_keys.value AS INTEGER) + excluded.value,\n version = stash_keys.version + 1\nRETURNING value;\n```\n\nThis is intentionally a sketch: the final statement must additionally reject\nexpired or wrong-type state correctly, reject non-canonical integers, preserve\nthe existing TTL when required by the counter contract, and prevent signed\n64-bit overflow without mutation.\n\n### Eventual first-class collection storage\n\nDedicated tables are the provisional direction for collection types; collections\nshould not be rewritten as monolithic JSON string values.\n\n```sql\nCREATE TABLE stash_hashes (\n key TEXT NOT NULL,\n field TEXT NOT NULL,\n value BLOB NOT NULL,\n PRIMARY KEY (key, field)\n);\n\nCREATE TABLE stash_sets (\n key TEXT NOT NULL,\n member BLOB NOT NULL,\n PRIMARY KEY (key, member)\n);\n\nCREATE TABLE stash_sorted_sets (\n key TEXT NOT NULL,\n member BLOB NOT NULL,\n score REAL NOT NULL,\n PRIMARY KEY (key, member)\n);\n\nCREATE INDEX stash_sorted_sets_order\n ON stash_sorted_sets(key, score, member);\n\nCREATE TABLE stash_stream_entries (\n key TEXT NOT NULL,\n id_ms INTEGER NOT NULL,\n id_seq INTEGER NOT NULL,\n fields TEXT NOT NULL,\n PRIMARY KEY (key, id_ms, id_seq)\n);\n```\n\nThese future schemas are incomplete. A later design must specify key-level type\nownership, TTL behavior across collection rows, deletion, empty-collection\nbehavior, and transactional coordination with `stash_keys` before\nimplementation.\n\n## Seams & Testing Decisions\n\n- **Primary seam: public TypeScript client API backed by real val-scoped\n SQLite.** Tests invoke public commands and observe their results and errors\n without reaching through the client to assert SQL statements or table layouts.\n This seam was confirmed because correctness depends on real database atomicity\n and transaction behavior.\n- Tests verify externally observable command behavior: missing keys, byte\n preservation, text and JSON round trips, conditional-write results, expiration\n visibility, integer parsing, return values, and wrong-type errors.\n- Concurrency tests issue overlapping operations against the same database and\n key. They must demonstrate that only one competing only-if-absent write\n succeeds and that no increments are lost.\n- Expiration tests use a controllable clock exposed through the library's\n internal construction boundary. They do not rely on wall-clock sleeping.\n- Cleanup tests demonstrate that cleanup removes eligible storage while leaving\n API behavior unchanged before and after cleanup.\n- Prefix tests assert that a prefixed client is equivalent to applying the\n prefix to keys through the unprefixed client.\n- Schema tests verify that initialization can run more than once and that\n supported migrations preserve existing data.\n- Unit tests may cover pure serialization, validation, and key-prefix behavior,\n but mocks are not sufficient for command correctness.\n- Future data types will be tested through the same public client seam,\n including wrong-type behavior and concurrent mutations.\n\n## Out of Scope\n\n- RESP or wire-protocol compatibility.\n- Compatibility with existing Redis client libraries.\n- Running a persistent TCP server.\n- Redis replication, clustering, persistence modes, eviction policies, or\n in-memory performance characteristics.\n- Pub/sub.\n- Lua scripts or Redis Functions.\n- Blocking list or stream operations.\n- Distributed locks with guarantees stronger than those explicitly provided by\n the library.\n- First-class JSON path operations.\n- First-class hashes, sets, sorted sets, lists, or streams in the first release.\n- Bitmaps and bitfields in the first release; these may later be added as\n operations over string values.\n- Geospatial indexes, HyperLogLog, Bloom filters, other probabilistic\n structures, time series, arrays, and vector sets.\n- A hybrid SQLite-and-Blob value backend. Cross-store writes cannot be made\n atomic and are deferred until large binary values provide a demonstrated need.\n- Automatic key namespacing, tenant security boundaries, or access control based\n on prefixes.\n- Exact Redis latency, memory use, maximum value size, or algorithmic-complexity\n guarantees.\n\n## Settled API Decisions\n\n1. The default `get` method returns decoded text for ergonomics, paired with\n explicit `getBytes` and `setBytes` methods; the internal representation\n remains binary-safe.\n2. Relative expiration uses the explicit `ttlMs` option, while `expiresAt`\n accepts an absolute instant.\n3. A successful ordinary set clears an existing TTL unless the caller requests\n `keepTtl`.\n4. Counters guarantee signed 64-bit integers; overflow produces an error without\n mutation.\n\n## Open Questions\n\n1. Should the first release expose key scanning? If included, it should be a\n cursor-based, non-blocking API with clearly documented pattern semantics; a\n whole-keyspace `keys` operation should not be encouraged.\n2. Should future streams include consumer groups? Basic streams should be\n designed first; consumer groups require separate design because their\n delivery and recovery semantics are substantial.\n\n## Further Notes\n\n- Val Town SQLite reference: https://docs.val.town/reference/std/sqlite/\n- Val Town SQLite usage: https://docs.val.town/reference/std/sqlite/usage/\n- Val Town Blob reference: https://docs.val.town/reference/std/blob/\n- Redis data type reference: https://redis.io/docs/latest/develop/data-types/\n- Redis-compatible behavior is a design guide, not a claim of complete\n compatibility.\n- The likely eventual general-purpose type set is string, hash, set, sorted set,\n list, and stream. Cross-cutting semantics such as atomicity, expiration, type\n safety, and conditional mutation take priority over expanding that set.\n","# Spec: Townstash\n\n## Problem Statement\n\nVal Town provides val-scoped SQLite and Blob storage, but neither offers the\nergonomic data-structure API, atomic counters, conditional writes, expiration\nbehavior, and familiar key operations associated with Redis.\n\nDevelopers who need caching, idempotency, rate limiting, counters, queues, or\nsmall shared data structures must repeatedly design storage schemas and\nconcurrency behavior themselves. A reusable Redis-inspired TypeScript library\nwould provide consistent semantics for these use cases without requiring an\nexternal Redis service.\n\nThe library must be honest about its scope. It is a persistent library backed by\nVal Town storage, not an in-memory Redis server, a RESP-compatible endpoint, or\na complete reimplementation of Redis performance and distributed-system\nbehavior.\n\n## Solution\n\nProvide **Townstash**, a Val Town library val that exports a Redis-inspired\nTypeScript API backed by val-scoped SQLite. Consumers import the library from\n`townstash` and interact with its canonical exported client, `stash`. The first\nversion will implement Redis-style string values, key expiration, conditional\nwrites, deletion, existence checks, atomic integer counters, JSON convenience\nmethods, and optional key-prefix helpers.\n\nValues at the core storage boundary are binary-safe sequences of bytes. Text and\nJSON APIs are conveniences layered over that representation. Numbers are not a\nseparate value type: integer operations interpret the current string value as an\ninteger, following the Redis model.\n\nThe library will preserve correctness under concurrent requests by expressing\natomic operations as atomic database operations. Expired keys will be treated as\nabsent during every command that observes key existence, regardless of whether\nbackground cleanup has run.\n\nFuture releases may add hashes, sets, sorted sets, lists, and streams as\nfirst-class value types. These types will not be simulated by silently storing\nmutable JSON documents under string keys.\n\n## User Stories\n\n1. As a Val author, I want to store and retrieve text values by key, so that I\n can persist simple application state.\n2. As a Val author, I want to store and retrieve arbitrary bytes, so that string\n values are binary-safe rather than limited to UTF-8 text.\n3. As a TypeScript developer, I want explicit text, byte, and JSON helpers, so\n that serialization behavior is predictable.\n4. As a Val author, I want missing and expired keys to produce the same\n observable result, so that expiration does not leak storage-cleanup details.\n5. As a Val author, I want to set a key only when it is absent, so that I can\n implement locks, idempotency claims, and first-writer-wins behavior.\n6. As a Val author, I want to set a key only when it is present, so that I can\n avoid accidentally creating state during an update.\n7. As a Val author, I want conditional writes to be atomic, so that concurrent\n requests cannot both succeed when only one should.\n8. As a Val author, I want to attach a time to live when setting a value, so\n that cache and coordination records expire automatically.\n9. As a Val author, I want to add, replace, inspect, and remove a key's\n expiration, so that lifecycle management is available independently of value\n updates.\n10. As a Val author, I want expiration checks to be correct even if no cleanup\n job has run, so that stale values never become visible.\n11. As a Val author, I want to delete one or more keys and learn how many\n existed, so that deletion has useful Redis-like return semantics.\n12. As a Val author, I want to check whether a key exists without retrieving its\n value, so that intent is clear and serialization work is avoided.\n13. As a Val author, I want to increment or decrement an integer value\n atomically, so that counters and rate limits remain correct under\n concurrency.\n14. As a Val author, I want increment and decrement methods to accept an\n optional signed integer amount, so that the API remains expressive and\n Redis-consistent.\n15. As a Val author, I want separate increment and decrement methods, so that\n the direction of a counter change is discoverable and readable.\n16. As a Val author, I want a missing counter to behave as zero before an\n increment or decrement, so that counters need no initialization request.\n17. As a Val author, I want numeric commands to reject non-integer string values\n without changing them, so that invalid counter state is not silently\n corrupted.\n18. As a Val author, I want keys to occupy one flat keyspace, so that the\n storage model matches Redis key semantics.\n19. As a Val author, I want an optional prefixing wrapper, so that I can\n organize application keys without introducing first-class namespace\n behavior.\n20. As a Val author, I want prefixing to be transparent and compositional, so\n that commands operate on the same underlying flat keyspace.\n21. As a Val author, I want to inspect a key's type, so that type errors can be\n diagnosed as additional first-class data types are introduced.\n22. As a Val author, I want commands applied to the wrong value type to fail\n consistently, so that data-model mistakes are visible.\n23. As a library maintainer, I want expired rows to be removable independently\n of command correctness, so that storage can be reclaimed without making\n cleanup timing part of the API contract.\n24. As a library maintainer, I want schema initialization to be idempotent, so\n that importing or initializing the library repeatedly is safe.\n25. As a library maintainer, I want atomic behavior tested against the real\n SQLite adapter, so that tests detect behavior that mocks cannot represent.\n26. As a library adopter, I want documented deviations from Redis, so that I do\n not assume unsupported server, networking, blocking, or performance\n semantics.\n27. As a future library user, I want hashes, sets, sorted sets, lists, and\n streams to have first-class commands and storage behavior, so that\n collections do not require unsafe read-modify-write cycles over JSON\n strings.\n28. As a Val author, I want to import `stash` from the `townstash` library val,\n so that setup is minimal and the API reads naturally at call sites.\n\n## Implementation Decisions\n\nThe durable architectural choices behind this implementation are recorded in:\n\n- [ADR-0001: Use val-scoped SQLite as the storage backend](../../adr/0001-use-val-scoped-sqlite.md)\n- [ADR-0002: Use a flat keyspace of binary-safe string values](../../adr/0002-flat-binary-safe-keyspace.md)\n- [ADR-0003: Determine command results atomically at execution time](../../adr/0003-command-correctness-at-execution-time.md)\n\n- The storage backend is val-scoped SQLite. Blob storage is not the primary\n backend because its documented interface does not provide the\n conditional-write, transactional, and atomic-update primitives required for\n Redis-like command semantics.\n- The product and library val are named **Townstash** and `townstash`,\n respectively.\n- The canonical public export is a ready-to-use client named `stash`.\n- Townstash is distributed as a Val Town library val rather than an npm, JSR, or\n standalone server package.\n- Account-global SQLite is not used by default. Each library instance operates\n within the SQLite database scoped to its val.\n- `stash` exposes a direct TypeScript API using familiar Redis-style command\n names where their semantics can be represented honestly. It does not implement\n the Redis Serialization Protocol or accept connections from existing Redis\n clients.\n- The keyspace is flat. A key contains its complete application-visible\n identifier, including any conventional prefix such as `cache:` or `session:`.\n- Namespace is not a persisted, first-class dimension of key identity.\n- An optional prefixing wrapper may prepend a configured string to every key\n passed through it. This is ergonomic sugar over the flat keyspace, not\n isolation or authorization.\n- The core first-version value type is the Redis string: a binary-safe byte\n sequence.\n- Text access is an explicit decoding convenience over byte values.\n- JSON access is an explicit serialization convenience over string values. JSON\n is not a first-class value type and does not provide path-level reads or\n mutations.\n- Integer counters are stored using string-compatible semantics rather than a\n separate public numeric type.\n- The public counter API provides both increment and decrement operations. Both\n accept an optional signed integer amount. Decrement is semantically equivalent\n to incrementing by the negated amount, so decrementing by a negative amount\n increments the value.\n- Numeric operations are atomic, treat a missing key as zero, and fail without\n mutation when the existing value is not a valid integer.\n- Conditional set behavior supports only-if-absent and only-if-present modes.\n Mutually incompatible options are rejected before execution.\n- Only-if-absent treats an expired key as absent. Only-if-present treats an\n expired key as absent.\n- Expiration is represented as an absolute instant. Public APIs may accept\n relative durations, but commands compare against a consistent current time\n when determining visibility.\n- Expiration is lazy for correctness: every relevant command excludes or\n replaces expired keys as appropriate.\n- Background or explicitly invoked cleanup is a storage-reclamation optimization\n only. Correctness never depends on its schedule.\n- Commands that combine existence checks and mutations must execute atomically.\n They must not use an application-level read followed by a separate write.\n- Multi-statement commands use the database's transactional batch capability\n when a single statement cannot express the required behavior.\n- Schema initialization is safe to run repeatedly and preserves v1 data. V1 does\n not expose a versioned migration path; future schema changes require an\n explicit migration design before they are supported.\n- The first version includes string get/set operations, byte and JSON\n conveniences, deletion, existence, expiration management, type inspection,\n conditional set, and integer increment/decrement.\n- Future first-class types are hashes, sets, sorted sets, lists, then streams.\n Each type receives dedicated data modeling and atomic commands rather than\n being encoded as a mutable JSON string.\n- Streams, if added, initially support persistent append and non-blocking reads.\n Blocking reads and consumer-group coordination require separate design work.\n- Redis compatibility is behavioral and selective. Command names and return\n conventions should remain familiar where doing so does not misrepresent the\n backend.\n\n## API and Data-Model Sketches\n\nThe following stubs capture decisions made during design. They are illustrative\nrather than final implementation prescriptions; names and return types may be\nrefined while preserving the documented behavior.\n\n### Intended usage\n\n```ts\nimport { stash } from \"townstash\";\n\nawait stash.set(\"user:123\", \"Alice\");\nawait stash.get(\"user:123\");\nawait stash.incr(\"views\");\nawait stash.del(\"user:123\");\n\nconst sessions = stash.withPrefix(\"session:\");\nawait sessions.set(\"abc\", \"payload\", { ttlMs: 60_000 });\nawait sessions.get(\"abc\");\n```\n\n`withPrefix` changes only how keys are presented to the underlying flat\nkeyspace. In the example, `sessions.get(\"abc\")` reads the stored key\n`session:abc`.\n\n`setJSON` stores `JSON.stringify(value)` as a UTF-8 string value, and rejects a\ntop-level value that serializes to `undefined`. `getJSON` parses the stored\nUTF-8 text and raises a `SyntaxError` when the value is not valid JSON. JSON\nhelpers do not add path-level reads or mutations.\n\nPrefix wrappers compose in call order: `stash.withPrefix(\"a:\").withPrefix(\"b:\")`\noperates on the flat key `a:b:`. A prefix is not persisted as a namespace\nor security boundary; the complete prefixed key remains directly addressable\nthrough an unprefixed client.\n\n### First-version client surface\n\n```ts\ntype StashValue = string | Uint8Array;\n\ninterface SetOptions {\n /** Expire the key this many milliseconds after command execution begins. */\n ttlMs?: number;\n\n /** Expire the key at this absolute instant. */\n expiresAt?: Date;\n\n /** Set only when the key is absent or expired. */\n nx?: boolean;\n\n /** Set only when the key exists and has not expired. */\n xx?: boolean;\n\n /** Preserve the current expiration when replacing an existing value. */\n keepTtl?: boolean;\n}\n\ninterface Stash {\n get(key: string): Promise;\n getBytes(key: string): Promise;\n\n set(\n key: string,\n value: StashValue,\n options?: SetOptions,\n ): Promise;\n\n setBytes(\n key: string,\n value: Uint8Array,\n options?: SetOptions,\n ): Promise;\n\n getJSON(key: string): Promise;\n setJSON(key: string, value: T, options?: SetOptions): Promise;\n\n del(...keys: string[]): Promise;\n exists(key: string): Promise;\n type(key: string): Promise<\"string\" | \"none\">;\n\n expire(key: string, ttlMs: number): Promise;\n expireAt(key: string, expiresAt: Date): Promise;\n persist(key: string): Promise;\n ttl(key: string): Promise;\n cleanup(): Promise;\n\n incr(key: string, by?: number | bigint): Promise;\n decr(key: string, by?: number | bigint): Promise;\n\n withPrefix(prefix: string): Stash;\n}\n\nexport const stash: Stash;\n```\n\nThe provisional `boolean` result for `set` means whether the write occurred. An\nunconditional valid set returns `true`; an unsatisfied `nx` or `xx` condition\nreturns `false`.\n\n`ttl` returns remaining milliseconds for a visible expiring key, `-1` for a\nvisible persistent key, and `undefined` for a missing or expired key. `cleanup`\nreturns the number of expired storage rows reclaimed; it does not change the\nvisibility rules used by ordinary commands.\n\n### Counter relationship\n\nBoth public counter methods share one atomic signed-increment primitive:\n\n```ts\nasync function decr(key: string, by: number | bigint = 1n): Promise {\n return incrementBy(key, counterDelta(by, -1n));\n}\n```\n\nSigned amounts remain valid. Consequently, decrementing by a negative amount\nincrements the stored value.\n\nThe exact result is a JavaScript `bigint`, not a `number`. Callers use bigint\nliterals for arithmetic and strict comparisons. Callers that require a `number`\nmust explicitly convert with `Number(result)` after verifying that the value is\nbetween `Number.MIN_SAFE_INTEGER` and `Number.MAX_SAFE_INTEGER`; conversion\noutside that range loses precision. Because `JSON.stringify` does not accept\n`bigint` directly, JSON consumers serialize the result as a decimal string or a\nsafely bounded `number`.\n\n### First-version key schema\n\nThe schema keeps one flat keyspace and reserves a type discriminator for future\nfirst-class data structures:\n\n```sql\nCREATE TABLE IF NOT EXISTS stash_keys (\n key TEXT PRIMARY KEY,\n type TEXT NOT NULL,\n value BLOB,\n expires_at INTEGER,\n version INTEGER NOT NULL DEFAULT 1\n);\n\nCREATE INDEX IF NOT EXISTS stash_keys_expiration\n ON stash_keys(expires_at)\n WHERE expires_at IS NOT NULL;\n```\n\n`expires_at` is an absolute Unix timestamp in milliseconds. `version` is\nreserved for mutation tracking and potential future compare-and-swap behavior;\nit need not be exposed in the first public API.\n\n### Lazy expiration\n\nReads treat expired records exactly like missing records:\n\n```sql\nSELECT type, value\nFROM stash_keys\nWHERE key = ?\n AND (expires_at IS NULL OR expires_at > ?);\n```\n\nCleanup exists only to reclaim storage:\n\n```sql\nDELETE FROM stash_keys\nWHERE expires_at IS NOT NULL\n AND expires_at <= ?;\n```\n\nEvery command whose behavior depends on existence must apply the same logical\nexpiration rule. In particular, `nx` may replace an expired row, while `xx`,\n`exists`, `type`, `expire`, `persist`, and `ttl` treat it as absent.\n\n### Atomic increment shape\n\nThe implementation should perform parsing, validation, arithmetic, overflow\nchecking, and mutation as one database operation. It must not read the value\ninto TypeScript and issue a separate write. The earlier design used the\nfollowing upsert shape as a starting point:\n\n```sql\nINSERT INTO stash_keys (key, type, value, expires_at)\nVALUES (?, 'string', ?, NULL)\nON CONFLICT(key) DO UPDATE SET\n value = CAST(stash_keys.value AS INTEGER) + excluded.value,\n version = stash_keys.version + 1\nRETURNING value;\n```\n\nThis is intentionally a sketch: the final statement must additionally reject\nexpired or wrong-type state correctly, reject non-canonical integers, preserve\nthe existing TTL when required by the counter contract, and prevent signed\n64-bit overflow without mutation.\n\n### Eventual first-class collection storage\n\nDedicated tables are the provisional direction for collection types; collections\nshould not be rewritten as monolithic JSON string values.\n\n```sql\nCREATE TABLE stash_hashes (\n key TEXT NOT NULL,\n field TEXT NOT NULL,\n value BLOB NOT NULL,\n PRIMARY KEY (key, field)\n);\n\nCREATE TABLE stash_sets (\n key TEXT NOT NULL,\n member BLOB NOT NULL,\n PRIMARY KEY (key, member)\n);\n\nCREATE TABLE stash_sorted_sets (\n key TEXT NOT NULL,\n member BLOB NOT NULL,\n score REAL NOT NULL,\n PRIMARY KEY (key, member)\n);\n\nCREATE INDEX stash_sorted_sets_order\n ON stash_sorted_sets(key, score, member);\n\nCREATE TABLE stash_stream_entries (\n key TEXT NOT NULL,\n id_ms INTEGER NOT NULL,\n id_seq INTEGER NOT NULL,\n fields TEXT NOT NULL,\n PRIMARY KEY (key, id_ms, id_seq)\n);\n```\n\nThese future schemas are incomplete. A later design must specify key-level type\nownership, TTL behavior across collection rows, deletion, empty-collection\nbehavior, and transactional coordination with `stash_keys` before\nimplementation.\n\n## Seams & Testing Decisions\n\n- **Primary seam: public TypeScript client API backed by real val-scoped\n SQLite.** Tests invoke public commands and observe their results and errors\n without reaching through the client to assert SQL statements or table layouts.\n This seam was confirmed because correctness depends on real database atomicity\n and transaction behavior.\n- Tests verify externally observable command behavior: missing keys, byte\n preservation, text and JSON round trips, conditional-write results, expiration\n visibility, integer parsing, return values, and wrong-type errors.\n- Concurrency tests issue overlapping operations against the same database and\n key. They must demonstrate that only one competing only-if-absent write\n succeeds and that no increments are lost.\n- Expiration tests use a controllable clock exposed through the library's\n internal construction boundary. They do not rely on wall-clock sleeping.\n- Cleanup tests demonstrate that cleanup removes eligible storage while leaving\n API behavior unchanged before and after cleanup.\n- Prefix tests assert that a prefixed client is equivalent to applying the\n prefix to keys through the unprefixed client.\n- Schema tests verify that initialization can run more than once and that\n supported migrations preserve existing data.\n- Unit tests may cover pure serialization, validation, and key-prefix behavior,\n but mocks are not sufficient for command correctness.\n- Future data types will be tested through the same public client seam,\n including wrong-type behavior and concurrent mutations.\n\n## Out of Scope\n\n- RESP or wire-protocol compatibility.\n- Compatibility with existing Redis client libraries.\n- Running a persistent TCP server.\n- Redis replication, clustering, persistence modes, eviction policies, or\n in-memory performance characteristics.\n- Pub/sub.\n- Lua scripts or Redis Functions.\n- Blocking list or stream operations.\n- Distributed locks with guarantees stronger than those explicitly provided by\n the library.\n- First-class JSON path operations.\n- First-class hashes, sets, sorted sets, lists, or streams in the first release.\n- Bitmaps and bitfields in the first release; these may later be added as\n operations over string values.\n- Geospatial indexes, HyperLogLog, Bloom filters, other probabilistic\n structures, time series, arrays, and vector sets.\n- A hybrid SQLite-and-Blob value backend. Cross-store writes cannot be made\n atomic and are deferred until large binary values provide a demonstrated need.\n- Automatic key namespacing, tenant security boundaries, or access control based\n on prefixes.\n- Exact Redis latency, memory use, maximum value size, or algorithmic-complexity\n guarantees.\n\n## Settled API Decisions\n\n1. The default `get` method returns decoded text for ergonomics, paired with\n explicit `getBytes` and `setBytes` methods; the internal representation\n remains binary-safe.\n2. Relative expiration uses the explicit `ttlMs` option, while `expiresAt`\n accepts an absolute instant.\n3. A successful ordinary set clears an existing TTL unless the caller requests\n `keepTtl`.\n4. Counters guarantee signed 64-bit integers and return exact `bigint` values;\n overflow produces an error without mutation. Consumers must explicitly and\n safely convert when a `number` or JSON-compatible representation is required.\n\n## Open Questions\n\n1. Should the first release expose key scanning? If included, it should be a\n cursor-based, non-blocking API with clearly documented pattern semantics; a\n whole-keyspace `keys` operation should not be encouraged.\n2. Should future streams include consumer groups? Basic streams should be\n designed first; consumer groups require separate design because their\n delivery and recovery semantics are substantial.\n\n## Further Notes\n\n- Val Town SQLite reference: https://docs.val.town/reference/std/sqlite/\n- Val Town SQLite usage: https://docs.val.town/reference/std/sqlite/usage/\n- Val Town Blob reference: https://docs.val.town/reference/std/blob/\n- Redis data type reference: https://redis.io/docs/latest/develop/data-types/\n- Redis-compatible behavior is a design guide, not a claim of complete\n compatibility.\n- The likely eventual general-purpose type set is string, hash, set, sorted set,\n list, and stream. Cross-cutting semantics such as atomicity, expiration, type\n safety, and conditional mutation take priority over expanding that set.\n","createdAt",["D",1783923547831],"branchVersion","branchId","21ed0900-d0ad-4fc5-824e-172e390e2e47","id","b2638454-5153-40e9-ae39-aa50d9897819","townstash",["D",1783830414588],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","Redis-style key/value storage for Val Town, backed by SQLite","imageUrl","5d1042a9-7b0b-499d-8a72-3a8ac7a4e185","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount",1,"orgId","5f80108f-7ca4-4327-b77b-089dbe4b5a82","tursoName","b2638454515340e9ae39aa50d9897819","tursoHostname","b2638454515340e9ae39aa50d9897819-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789526460011],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_98":97,"_105":101},"org",{"_98":97,"_99":-5,"_100":101,"_18":55,"_102":103,"_104":25},"branch",{"_13":87,"_32":88,"_43":42,"_89":44,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":45,"_96":97},"isOwned",275,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","nbbaier","handle","displayName","avatar","https://secure.gravatar.com/avatar/0129a541b7b3574e92c4afd06c5e32da&d=identicon","tier","pro","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_43":44,"_32":45,"_38":580,"_47":-5,"_48":25,"_49":50,"_51":50,"_52":53,"_54":-5,"_18":55,"_56":-5,"_57":25,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":65,"_66":67,"_68":581,"_70":-5,"_71":72,"_73":72,"_74":75,"_76":75,"_77":75,"_78":72,"_79":72,"_80":582,"_82":583,"_84":584,"_86":25},"tree",[236,270,273,274,275,276,277,278,279,280,281],"files",[236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273,274,275,276,277,278,279,280,281],"counts",{"_226":196,"_227":61,"_228":196,"_229":230,"_231":232},"contents",[128,129,130,131,132,133,134,135,136,137,138],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_43":220,"_32":221,"_30":222,"_142":-5,"_41":42,"_40":223,"_144":171,"_38":224,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_27":225},{"_43":213,"_32":214,"_30":215,"_142":-5,"_41":42,"_40":216,"_144":171,"_38":217,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_27":219},{"_43":206,"_32":207,"_30":208,"_142":-5,"_41":42,"_40":209,"_144":171,"_38":210,"_13":196,"_34":20,"_35":211,"_24":25,"_149":-5,"_27":212},{"_43":199,"_32":200,"_30":201,"_142":-5,"_41":42,"_40":202,"_144":171,"_38":203,"_13":204,"_34":20,"_35":189,"_24":25,"_149":-5,"_27":205},{"_43":191,"_32":192,"_30":193,"_142":-5,"_41":42,"_40":194,"_144":171,"_38":195,"_13":196,"_34":20,"_35":197,"_24":25,"_149":-5,"_27":198},{"_43":183,"_32":184,"_30":185,"_142":-5,"_41":42,"_40":186,"_144":171,"_38":187,"_13":188,"_34":20,"_35":189,"_24":25,"_149":-5,"_27":190},{"_43":175,"_32":176,"_30":177,"_142":-5,"_41":42,"_40":178,"_144":25,"_38":179,"_13":180,"_34":20,"_35":181,"_24":25,"_149":-5,"_27":182},{"_43":167,"_32":168,"_30":169,"_142":-5,"_41":42,"_40":170,"_144":171,"_38":172,"_13":61,"_34":147,"_35":173,"_24":25,"_149":-5,"_27":174},{"_43":159,"_32":160,"_30":161,"_142":-5,"_41":42,"_40":162,"_144":25,"_38":163,"_13":164,"_34":20,"_35":165,"_24":25,"_149":-5,"_27":166},{"_43":151,"_32":152,"_30":153,"_142":-5,"_41":42,"_40":154,"_144":25,"_38":155,"_13":156,"_34":147,"_35":157,"_24":25,"_149":-5,"_27":158},{"_43":139,"_32":140,"_30":141,"_142":-5,"_41":42,"_40":143,"_144":25,"_38":145,"_13":146,"_34":147,"_35":148,"_24":25,"_149":-5,"_27":150},"1ac8cf77-78d5-4b43-abb1-eb6d0f2244b9","main_test.ts","59f9b368-7e06-11f1-b945-1607ee4eb77e","parentId",218,"latest",["D",1783923547434],23,"script","import { stash } from \"./main.ts\";\n\nconst v1Commands = [\n \"cleanup\",\n \"decr\",\n \"del\",\n \"expire\",\n \"expireAt\",\n \"exists\",\n \"get\",\n \"getBytes\",\n \"getJSON\",\n \"incr\",\n \"persist\",\n \"set\",\n \"setBytes\",\n \"setJSON\",\n \"ttl\",\n \"type\",\n \"withPrefix\",\n];\n\ntype TestCase = {\n name: string;\n ignore?: boolean;\n fn: () => void | Promise;\n};\n\nconst tests: TestCase[] = [\n {\n name: \"the library entry point exports exactly the v1 stash client\",\n fn() {\n const actualCommands = Object.keys(stash).sort();\n const expectedCommands = [...v1Commands].sort();\n if (JSON.stringify(actualCommands) !== JSON.stringify(expectedCommands)) {\n throw new Error(\n `Expected v1 commands ${JSON.stringify(expectedCommands)}, got ${\n JSON.stringify(\n actualCommands,\n )\n }`,\n );\n }\n\n for (const command of v1Commands) {\n if (typeof stash[command as keyof typeof stash] !== \"function\") {\n throw new Error(`Expected stash.${command} to be callable`);\n }\n }\n },\n },\n {\n name: \"the published stash client completes a v1 workflow in Val Town\",\n ignore: Deno.env.get(\"TOWNSTASH_LIVE_INTEGRATION\") !== \"1\",\n async fn() {\n const client = stash.withPrefix(\n `__townstash_v1__:${crypto.randomUUID()}:`,\n );\n const keys = [\"text\", \"bytes\", \"json\", \"counter\"];\n console.log(\"[live] Townstash hosted integration started\");\n try {\n if (!(await client.set(\"text\", \"Ada\", { nx: true, ttlMs: 60_000 }))) {\n throw new Error(\"Expected the live integration claim to succeed\");\n }\n if ((await client.get(\"text\")) !== \"Ada\") {\n throw new Error(\"Expected the live text value to round-trip\");\n }\n console.log(\"[live] text and conditional write passed\");\n await client.setBytes(\"bytes\", new Uint8Array([0, 255, 128]));\n if (\n JSON.stringify(Array.from((await client.getBytes(\"bytes\")) ?? [])) !==\n \"[0,255,128]\"\n ) {\n throw new Error(\"Expected the live byte value to round-trip\");\n }\n console.log(\"[live] binary-safe bytes passed\");\n await client.setJSON(\"json\", { ready: true });\n if (\n (await client.getJSON<{ ready: boolean }>(\"json\"))?.ready !== true\n ) {\n throw new Error(\"Expected the live JSON value to round-trip\");\n }\n console.log(\"[live] JSON helpers passed\");\n if ((await client.incr(\"counter\", 2)) !== 2n) {\n throw new Error(\"Expected the live counter to increment\");\n }\n if ((await client.decr(\"counter\")) !== 1n) {\n throw new Error(\"Expected the live counter to decrement\");\n }\n console.log(\"[live] atomic counter operations passed\");\n if ((await client.del(\"text\", \"bytes\", \"json\", \"counter\")) !== 4) {\n throw new Error(\n \"Expected the live workflow cleanup to remove four keys\",\n );\n }\n console.log(\"[live] deletion and cleanup passed\");\n console.log(\"[live] Townstash hosted integration passed\");\n } finally {\n await client.del(...keys);\n }\n },\n },\n];\n\nasync function runTests(): Promise {\n let passed = 0;\n let failed = 0;\n let skipped = 0;\n\n for (const test of tests) {\n if (test.ignore) {\n console.log(`- ${test.name} ... ignored`);\n skipped++;\n continue;\n }\n try {\n await test.fn();\n console.log(`✓ ${test.name}`);\n passed++;\n } catch (error) {\n console.error(`✗ ${test.name}`);\n console.error(error);\n failed++;\n }\n }\n\n console.log(\n `\\n${passed} passed, ${failed} failed, ${skipped} ignored (of ${tests.length})`,\n );\n\n if (failed > 0) {\n throw new Error(`${failed} test(s) failed`);\n }\n}\n\nawait runTests();\n","label",[140],"55d938b7-981a-483d-89bb-3d3450e2f992","main.ts","1a013e48-7db6-11f1-b08c-1607ee4eb77e",108,["D",1783874292383],5,"import { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\n\nimport { createStash } from \"./src/stash.ts\";\n\nexport type { SetOptions, Stash, StashValue } from \"./src/stash.ts\";\n\n/** The ready-to-use Townstash client backed by this val's SQLite database. */\nexport const stash = createStash(sqlite);\n",[152],"b09f024b-1b53-44f5-b862-73e636240314","deno.json","36597c4a-7dac-11f1-8c55-1607ee4eb77e",163,["D",1783880366517],7,"{\n \"compilerOptions\": {\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"dom.asynciterable\",\n \"deno.ns\",\n \"deno.unstable\"\n ],\n \"noImplicitAny\": true,\n \"strict\": true,\n \"types\": [\"https://www.val.town/types/valtown.d.ts\"]\n },\n \"experimental\": {\n \"unstable-node-globals\": true,\n \"unstable-sloppy-imports\": true,\n \"unstable-temporal\": true,\n \"unstable-worker-options\": true\n },\n \"tasks\": {\n \"lint\": \"deno lint\",\n \"check\": \"deno fmt && deno task lint && deno check --allow-import main.ts main_test.ts src/stash.ts src/stash_test.ts\",\n \"test\": \"deno test --allow-all\"\n },\n \"lint\": {\n \"include\": [\"deno:/https/esm.town/**/*\", \"src/\", \"main.ts\", \"main_test.ts\"],\n \"rules\": { \"exclude\": [\"no-explicit-any\", \"no-import-prefix\"] }\n },\n \"lock\": false,\n \"nodeModulesDir\": \"auto\"\n}\n",[160],"17553072-be04-411a-bc29-61f196428c83","bench.ts","e3eac08a-7e1f-11f1-b9f7-1607ee4eb77e",165,true,["D",1783881460722],"// Benchmark Townstash (val-scoped SQLite) against val-scoped blob storage.\n//\n// This is a plain-script val, not a Deno.test suite, because it must run on\n// Val Town to measure the real server->storage latency of each backend. See\n// docs/adr/0004-plain-script-tests-for-val-town.md. Run it as a one-shot val\n// (its own endpoint / \"Run\") and read the printed tables from the logs.\n//\n// Every op here is a network round trip, so numbers measured from a laptop are\n// meaningless — only the hosted run reflects reality. A unique key prefix keeps\n// runs isolated, and the finally block reclaims every key it created.\n//\n// Each latency figure is the MEDIAN across REPEATS independent runs (with the\n// per-run p50 min–max shown as spread), to smooth run-to-run tail variance.\n\nimport { stash } from \"./main.ts\";\nimport { blob } from \"https://esm.town/v/std/blob/main.ts\";\n\nconst ITERS = 50;\nconst WARMUP = 5;\nconst REPEATS = 3;\nconst WIDTHS = [1, 5, 10, 20, 50];\n\ntype Stats = { p50: number; p95: number; p99: number; mean: number };\ntype Agg = Stats & { p50min: number; p50max: number; runs: number };\n\nconst median = (xs: number[]): number => {\n const s = [...xs].sort((a, b) => a - b);\n return s[Math.floor(s.length / 2)];\n};\n\n/**\n * Time `fn` over `iters` samples after discarding `warmup` runs. `fn` receives\n * a monotonically increasing index (0..warmup-1 for warmup, then warmup..) so\n * callers that must not reuse state per call (e.g. delete) can key off it.\n */\nasync function measure(\n fn: (i: number) => Promise,\n iters = ITERS,\n warmup = WARMUP,\n): Promise {\n for (let i = 0; i < warmup; i++) await fn(i);\n const samples: number[] = [];\n for (let i = 0; i < iters; i++) {\n const start = performance.now();\n await fn(warmup + i);\n samples.push(performance.now() - start);\n }\n samples.sort((a, b) => a - b);\n const at = (p: number) =>\n samples[\n Math.min(samples.length - 1, Math.floor((p / 100) * samples.length))\n ];\n const mean = samples.reduce((a, b) => a + b, 0) / samples.length;\n return { p50: at(50), p95: at(95), p99: at(99), mean };\n}\n\n/** Run `measure` REPEATS times and report the median of each stat + p50 spread. */\nasync function aggregate(\n fn: (i: number) => Promise,\n iters = ITERS,\n warmup = WARMUP,\n): Promise {\n const runs: Stats[] = [];\n for (let r = 0; r < REPEATS; r++) runs.push(await measure(fn, iters, warmup));\n const p50s = runs.map((s) => s.p50);\n return {\n p50: median(p50s),\n p95: median(runs.map((s) => s.p95)),\n p99: median(runs.map((s) => s.p99)),\n mean: median(runs.map((s) => s.mean)),\n p50min: Math.min(...p50s),\n p50max: Math.max(...p50s),\n runs: REPEATS,\n };\n}\n\n/** Time one batch of `width` concurrent calls; report the batch's ops/sec. */\nasync function throughput(\n make: (i: number) => Promise,\n width: number,\n batches = 5,\n): Promise<{ opsPerSec: number; meanBatchMs: number; ops: number }> {\n await Promise.all(Array.from({ length: width }, (_, i) => make(i))); // warm\n const durations: number[] = [];\n for (let b = 0; b < batches; b++) {\n const start = performance.now();\n await Promise.all(\n Array.from({ length: width }, (_, i) => make((b + 1) * width + i)),\n );\n durations.push(performance.now() - start);\n }\n const meanBatchMs = durations.reduce((a, b) => a + b, 0) / durations.length;\n return {\n opsPerSec: (width / meanBatchMs) * 1000,\n meanBatchMs,\n ops: width * batches,\n };\n}\n\nconst fmt = (a: Agg) =>\n `p50 ${a.p50.toFixed(1)}ms [${a.p50min.toFixed(1)}–${\n a.p50max.toFixed(1)\n }] ` +\n `p95 ${a.p95.toFixed(1)}ms p99 ${a.p99.toFixed(1)}ms mean ${\n a.mean.toFixed(1)\n }ms ` +\n `(median of ${a.runs}×${ITERS})`;\n\nconst ns = `__townstash_bench__:${crypto.randomUUID()}:`;\nconst createdStashKeys = new Set();\nconst createdBlobKeys = new Set();\n\nasync function stashSet(key: string, value: string) {\n createdStashKeys.add(key);\n await stash.set(key, value);\n}\nasync function blobSet(key: string, value: string) {\n createdBlobKeys.add(key);\n await blob.set(key, value);\n}\n\nconst SIZES: Record = {\n small: 64,\n medium: 4_096,\n large: 262_144,\n};\n\nconsole.log(`Townstash vs blob benchmark (namespace ${ns})`);\nconsole.log(`config: iters=${ITERS} warmup=${WARMUP} repeats=${REPEATS}`);\nconsole.log(\"=\".repeat(72));\n\ntry {\n // --- Core set / get across payload sizes -------------------------------\n for (const [label, bytes] of Object.entries(SIZES)) {\n const value = \"x\".repeat(bytes);\n const sk = `${ns}core:s:${label}`;\n const bk = `${ns}core:b:${label}`;\n\n console.log(`\\n[set] ${label} (${bytes}B)`);\n console.log(` stash ${fmt(await aggregate(() => stashSet(sk, value)))}`);\n console.log(` blob ${fmt(await aggregate(() => blobSet(bk, value)))}`);\n\n console.log(`[get] ${label} (${bytes}B)`);\n console.log(` stash ${fmt(await aggregate(() => stash.get(sk)))}`);\n console.log(\n ` blob ${\n fmt(await aggregate(() => blob.get(bk).then((r) => r.text())))\n }`,\n );\n }\n\n // --- del (isolated: pre-seed keys, time the delete only) ---------------\n // Each repeat pre-seeds WARMUP+ITERS keys up front, so the timed section is a\n // pure single-key delete — not the set+del pair the first draft measured.\n console.log(\"\\n[del] (pre-seeded keys, delete only)\");\n const isolatedDelete = (\n seed: (k: string) => Promise,\n kill: (k: string) => Promise,\n tag: string,\n ) =>\n (async (): Promise => {\n const runs: Stats[] = [];\n for (let r = 0; r < REPEATS; r++) {\n const keys: string[] = [];\n for (let i = 0; i < WARMUP + ITERS; i++) {\n const k = `${ns}del:${tag}:${r}:${i}`;\n await seed(k);\n keys.push(k);\n }\n // Not registered for cleanup: the measured deletes remove them.\n runs.push(await measure((i) => kill(keys[i])));\n }\n const p50s = runs.map((s) => s.p50);\n return {\n p50: median(p50s),\n p95: median(runs.map((s) => s.p95)),\n p99: median(runs.map((s) => s.p99)),\n mean: median(runs.map((s) => s.mean)),\n p50min: Math.min(...p50s),\n p50max: Math.max(...p50s),\n runs: REPEATS,\n };\n })();\n console.log(\n ` stash ${\n fmt(\n await isolatedDelete(\n (k) => stash.set(k, \"v\"),\n (k) => stash.del(k),\n \"s\",\n ),\n )\n }`,\n );\n console.log(\n ` blob ${\n fmt(\n await isolatedDelete(\n (k) => blob.set(k, \"v\"),\n (k) => blob.delete(k),\n \"b\",\n ),\n )\n }`,\n );\n\n // --- JSON helpers ------------------------------------------------------\n const doc = {\n name: \"Ada\",\n roles: [\"admin\", \"editor\"],\n count: 42,\n nested: { ok: true },\n };\n const jsk = `${ns}json:s`;\n const jbk = `${ns}json:b`;\n createdStashKeys.add(jsk);\n createdBlobKeys.add(jbk);\n console.log(\"\\n[setJSON]\");\n console.log(\n ` stash ${fmt(await aggregate(() => stash.setJSON(jsk, doc)))}`,\n );\n console.log(` blob ${fmt(await aggregate(() => blob.setJSON(jbk, doc)))}`);\n console.log(\"[getJSON]\");\n console.log(` stash ${fmt(await aggregate(() => stash.getJSON(jsk)))}`);\n console.log(` blob ${fmt(await aggregate(() => blob.getJSON(jbk)))}`);\n\n // --- Counter: atomic incr vs blob read-modify-write --------------------\n // stash.incr is one atomic round trip. Blob has no counter primitive, so the\n // equivalent is get -> +1 -> set: two round trips AND racy under concurrency.\n const csk = `${ns}counter:s`;\n const cbk = `${ns}counter:b`;\n createdStashKeys.add(csk);\n createdBlobKeys.add(cbk);\n await stash.set(csk, \"0\");\n await blob.setJSON(cbk, 0);\n console.log(\"\\n[counter increment]\");\n console.log(\n ` stash.incr (atomic, 1 RT) ${\n fmt(await aggregate(() => stash.incr(csk)))\n }`,\n );\n console.log(\n ` blob RMW (racy, 2 RT) ${\n fmt(\n await aggregate(async () => {\n const n = (await blob.getJSON(cbk)) ?? 0;\n await blob.setJSON(cbk, n + 1);\n }),\n )\n }`,\n );\n\n // --- Concurrent throughput sweep (small set) ---------------------------\n // Maps where SQLite's single-writer wall hits relative to blob object storage.\n console.log(\"\\n[concurrent set throughput] width sweep, 5 batches each\");\n console.log(\" width stash ops/s blob ops/s ratio(blob/stash)\");\n for (const w of WIDTHS) {\n const st = await throughput(\n (i) => stashSet(`${ns}tput:s:${w}:${i}`, \"payload\"),\n w,\n );\n const bt = await throughput(\n (i) => blobSet(`${ns}tput:b:${w}:${i}`, \"payload\"),\n w,\n );\n console.log(\n ` ${String(w).padStart(5)} ${\n st.opsPerSec.toFixed(0).padStart(10)\n } ` +\n `${bt.opsPerSec.toFixed(0).padStart(10)} ${\n (bt.opsPerSec / st.opsPerSec).toFixed(2)\n }×`,\n );\n }\n} finally {\n // Reclaim everything this run created.\n if (createdStashKeys.size > 0) await stash.del(...createdStashKeys);\n await Promise.all(\n [...createdBlobKeys].map((k) => blob.delete(k).catch(() => {})),\n );\n console.log(\n `\\ncleanup: removed ${createdStashKeys.size} stash keys, ${createdBlobKeys.size} blob keys`,\n );\n}\n",[168],"c788c43c-fd1c-4021-bfe6-db0c127fd6a6","README.md","c298fd10-7e16-11f1-94c9-1607ee4eb77e",200,["D",1783897351819],14,"# Townstash\n\nTownstash is a Redis-inspired library for Val Town. It stores binary-safe string\nvalues in the SQLite database scoped to the library val and exports a\nready-to-use client named `stash`.\n\nTownstash is persistent application storage, not an in-memory Redis server. It\ndoes not expose RESP, accept connections from Redis clients, or promise Redis\nlatency, memory use, or distributed-system behavior.\n\n## Why Townstash over blob or raw SQLite\n\nVal Town gives every val two other scoped persistence options — `std/blob` and\n`std/sqlite`. Townstash competes with each on a different axis.\n\n### vs. `std/blob` (a performance argument)\n\nBoth are val-scoped key/value stores, so the comparison is speed. Benchmarks\n(see [`BENCHMARKS.md`](./BENCHMARKS.md)) show:\n\n- **Reads are ~3× faster** than blob at every payload size tested, up to 256 KB.\n- **Counters are ~2× faster and atomic** — `stash.incr` is one round trip, while\n the blob equivalent is a racy get→modify→set pair.\n- **Single writes and deletes are a tie** with blob.\n\nReach for blob instead when you need high concurrent write throughput (SQLite's\nsingle-writer model plateaus around 30–50 writes/sec, where blob scales 2–3×\nhigher) or are storing large opaque assets.\n\n### vs. `std/sqlite` (a convenience argument)\n\nTownstash _is_ a thin layer over `std/sqlite` — the same backend, so performance\nis essentially identical (there's nothing to benchmark). What it adds is a\nRedis-shaped key/value API over that backend so you don't hand-roll one:\n\n- Binary-safe get/set, JSON helpers, and canonical 64-bit counters over a flat\n keyspace — no schema, table, or migration to manage.\n- Existence-dependent operations decided **atomically at execution time**:\n conditional writes (`nx`/`xx`), `incr`/`decr`, and TTL expiration, instead of\n racy application-level read-then-write SQL.\n- Composable key prefixes for organizing the keyspace.\n\nReach for raw `std/sqlite` when your data is genuinely relational — multiple\ncolumns, joins, ad-hoc queries, secondary indexes — rather than values addressed\nby a single key.\n\nThe three are complementary: Townstash for keyed reads, counters, and small\nstructured values; blob for bulk writes and big files; raw SQLite when you need\nSQL.\n\n## Usage\n\nImport the canonical client from the `townstash` library val:\n\n```ts\nimport { stash } from \"townstash\";\n\nawait stash.set(\"greeting\", \"Hello, Val Town!\");\nconst greeting = await stash.get(\"greeting\"); // string | undefined\n\nconst bytes = new Uint8Array([0, 255, 128, 1]);\nawait stash.setBytes(\"payload\", bytes);\nconst storedBytes = await stash.getBytes(\"payload\");\n\nawait stash.setJSON(\"user:123\", { name: \"Ada\", roles: [\"admin\"] });\nconst user = await stash.getJSON<{ name: string; roles: string[] }>(\"user:123\");\n```\n\n`get` decodes a stored value as UTF-8 text. Use `getBytes` and `setBytes` when\nthe value is arbitrary binary data. JSON helpers use `JSON.stringify` and\n`JSON.parse` over the same string representation. A top-level value that\nserializes to `undefined` is rejected, and malformed stored JSON raises a\n`SyntaxError`.\n\n## Writes and key lifecycle\n\n`set` and `setBytes` return `true` when they write and `false` when a condition\nprevents the write:\n\n```ts\nconst claimed = await stash.set(\"job:123\", \"claimed\", {\n nx: true,\n ttlMs: 30_000,\n});\n\nawait stash.set(\"job:123\", \"finished\", { xx: true, keepTtl: true });\n\nawait stash.expire(\"job:123\", 60_000);\nawait stash.expireAt(\"job:123\", new Date(Date.now() + 60_000));\nconst remainingMs = await stash.ttl(\"job:123\");\nawait stash.persist(\"job:123\");\n```\n\n`nx` means only if absent and `xx` means only if present. They are mutually\nexclusive. `ttlMs` is relative to the timestamp sampled immediately before the\natomic database command executes; `expiresAt` is an absolute `Date`; the two\nexpiration forms are mutually exclusive. A normal replacement clears an existing\nexpiration unless `keepTtl` is supplied.\n\nExpiration is lazy. Every command that observes existence treats a key whose\nexpiration is at or before the current time as missing, even when its SQLite row\nhas not been cleaned up. `ttl` returns the remaining milliseconds for a visible\nexpiring key, `-1` for a visible persistent key, and `undefined` for a missing\nor expired key. `exists` returns a boolean, `type` returns `\"string\"` or\n`\"none\"`, and `del` returns the number of visible keys removed:\n\n```ts\nif (await stash.exists(\"job:123\")) {\n console.log(await stash.type(\"job:123\"));\n}\n\nconst removed = await stash.del(\"job:123\", \"job:missing\");\nawait stash.cleanup(); // storage reclamation; not required for correctness\n```\n\n## Counters and prefixes\n\nCounters are string values interpreted as canonical signed 64-bit integers.\nMissing and expired keys start at zero. `incr` and `decr` accept optional signed\ninteger amounts, preserve a visible expiration, and return the resulting\ninteger:\n\n```ts\nconst visits = await stash.incr(\"visits\");\nawait stash.incr(\"visits\", 4);\nawait stash.decr(\"visits\", 2);\nawait stash.decr(\"visits\", -1); // increments by one\n```\n\nNon-integer values, non-integer amounts, wrong-type values, and signed 64-bit\noverflow fail without mutating the stored value.\n\nPrefixes are transparent key helpers over one flat keyspace:\n\n```ts\nconst sessions = stash.withPrefix(\"session:\");\nawait sessions.set(\"abc\", \"payload\");\nawait stash.get(\"session:abc\");\n\nconst versioned = sessions.withPrefix(\"v1:\");\nawait versioned.set(\"abc\", \"next\"); // stores session:v1:abc\n```\n\nA prefix is not a persisted namespace, isolation boundary, or authorization\nmechanism. The complete prefixed key remains directly addressable through an\nunprefixed client.\n\n## v1 contract\n\n- The keyspace is flat. The v1 value type is a binary-safe byte sequence; text,\n JSON, and counters are conveniences or interpretations of that value.\n- Conditional writes, counter updates, and other existence-dependent commands\n determine their result atomically at SQLite execution time. Application-level\n read-then-write sequences are not part of the correctness guarantee.\n- Each library-val instance uses its own val-scoped SQLite database. Schema\n initialization is idempotent and preserves existing v1 rows when repeated. v1\n has no versioned migration path; future schema changes must add an explicit\n migration before they are supported.\n- `stash` includes string and byte reads/writes, JSON helpers, conditional\n writes, deletion, existence and type inspection, expiration management,\n cleanup, counters, and compositional prefixes.\n\nTownstash deliberately does not provide RESP or server compatibility, blocking\noperations, pub/sub, Lua or Redis Functions, replication, clustering, eviction\npolicies, distributed locks stronger than the documented atomic commands, or\nfirst-class hashes, sets, sorted sets, lists, and streams in v1. Those\ncollection types require dedicated storage and command semantics rather than\nmutable JSON strings.\n",[176],"a29aaa46-7975-4648-bf76-b5099f41643e","CLAUDE.md","3fe7f42c-7dba-11f1-adbf-1607ee4eb77e",157,["D",1783879967783],3,"## Agent skills\n\n### Issue tracker\n\nIssues and PRDs live as markdown files under `docs/issues//`. See\n`docs/agents/issue-tracker.md`.\n\n### Triage labels\n\nDefault label vocabulary (`needs-triage`, `needs-info`, `ready-for-agent`,\n`ready-for-human`, `wontfix`) used as-is. See `docs/agents/triage-labels.md`.\n\n### Domain docs\n\nSingle-context: one `CONTEXT.md` + `docs/adr/` at the repo root. See\n`docs/agents/domain.md`.\n\n## Testing\n\nTests split by where they run. Local unit tests (like `src/stash_test.ts`) use\n`Deno.test` and run with `deno test`. Tests that must run on Val Town (like\n`main_test.ts`) use a plain top-level script runner instead. See\n`docs/adr/0004-plain-script-tests-for-val-town.md`.\n",[184],"98f9c675-565b-4843-8c2d-06a1f6856412","BENCHMARKS.md","97477f04-7e22-11f1-af5c-1607ee4eb77e",169,["D",1783882245610],0,"# Townstash vs blob storage benchmarks\n\nTownstash and Val Town's `std/blob` are both val-scoped, network-backed\npersistence layers, so \"which is faster\" has a real answer for a given workload.\nThis document records that comparison. The harness is `bench.ts` at the repo\nroot; regenerate these numbers by running it on Val Town (not locally — every\noperation is a network round trip, so laptop measurements only time your own\nuplink, not the backend).\n\n## Method\n\n`bench.ts` is a plain-script val (see\n`docs/adr/0004-plain-script-tests-for-val-town.md`). For each operation it\ndiscards a warmup, times 50 samples, and repeats that 3 times, reporting the\n**median across runs** of p50/p95/p99/mean. Latency rows show a `[min–max]`\nbracket next to the median p50: the spread of the three runs' own p50s, so\nrun-to-run noise is visible rather than hidden behind a single number. Every key\nis written under a per-run UUID prefix and deleted in a `finally` block.\n\nOperations covered: core `set`/`get` at 64 B / 4 KB / 256 KB, isolated `del`\n(keys pre-seeded so only the delete is timed), JSON helpers, counter increment\n(atomic `stash.incr` vs a blob get→+1→set), and a concurrent-write throughput\nsweep at width 1/5/10/20/50.\n\nCaveats: single machine, single region, one sitting. The p95/p99 tails are noisy\n— treat them as order-of-magnitude, not precise. Rankings below hold only where\nthe `[min–max]` spread is tight; where it is wide (e.g. `setJSON`) the two\nbackends are effectively tied.\n\n## Results\n\nLatencies are median-of-3-runs p50, in milliseconds. Lower is better; **bold**\nmarks a clear winner (gap larger than the run-to-run spread).\n\n| Operation | stash (ms) | blob (ms) | Winner |\n| ----------------- | ---------: | --------: | ------------- |\n| set 64 B | 46.0 | 47.0 | tie |\n| get 64 B | **19.7** | 60.0 | **stash ~3×** |\n| set 4 KB | 39.9 | 48.9 | tie |\n| get 4 KB | **13.2** | 35.9 | **stash ~3×** |\n| set 256 KB | 42.5 | 48.1 | tie |\n| get 256 KB | **13.3** | 40.9 | **stash ~3×** |\n| del (isolated) | 27.3 | 26.1 | tie |\n| setJSON | 42.6 | 49.9 | tie (noisy) |\n| getJSON | **12.5** | 44.7 | **stash ~3×** |\n| counter increment | **45.8** | 101.9 | **stash ~2×** |\n\nConcurrent set throughput (ops/sec, higher is better):\n\n| Width | stash | blob | blob / stash |\n| ----: | ----: | ---: | -----------: |\n| 1 | 31 | 20 | 0.64× |\n| 5 | 30 | 62 | 2.08× |\n| 10 | 45 | 108 | 2.41× |\n| 20 | 48 | 78 | 1.64× |\n| 50 | 52 | 139 | 2.70× |\n\n(An earlier single-run pass showed the same shape — stash ahead at width 1, blob\n2–4× ahead by width 20+. The width-20 dip above is run noise, not a reversal.)\n\n## Findings\n\n- **Reads favor Townstash decisively — even for large values.** `get`/`getJSON`\n are ~3× faster across all payload sizes, including 256 KB (13 vs 41 ms).\n SQLite reads out of a warm val-scoped database beat an object-storage fetch at\n every size tested.\n- **Single writes are a tie.** `set` at all sizes lands within the run-to-run\n spread of blob. Neither backend is meaningfully faster for one write at a\n time.\n- **`del` is a tie** (~27 ms) once measured in isolation. (A combined set+del\n pass reads as ~2× that — don't mistake it for delete latency.)\n- **The atomic counter is ~2× faster and correct.** `stash.incr` is one atomic\n round trip; the blob equivalent is get→+1→set — two round trips _and_ racy\n under concurrency, so the latency gap understates the real difference.\n- **Blob wins concurrent write throughput.** Past ~5 concurrent writers blob\n pulls 2–3× ahead while Townstash plateaus around 30–52 ops/s. That ceiling is\n SQLite's single-writer model: concurrent writes serialize on one connection,\n whereas object storage fans them out. At width 1, stash's lower per-op latency\n still wins.\n\n**Bottom line:** reach for Townstash on read-heavy, counter-heavy, or\nlow-write-concurrency workloads; reach for blob when you need high concurrent\nwrite throughput or are storing large opaque assets. They are complementary, not\nsubstitutes.\n\nRaw run logs:\n\n- [`docs/benchmarks/2026-07-12-run-1-initial-draft.txt`](./docs/benchmarks/2026-07-12-run-1-initial-draft.txt)\n — first pass; single run, `del` measured as set+del.\n- [`docs/benchmarks/2026-07-12-run-2-tightened.txt`](./docs/benchmarks/2026-07-12-run-2-tightened.txt)\n — the run the tables above report.\n\nRe-run `bench.ts` on Val Town to reproduce.\n",[192],"2ce03feb-8f0e-4183-a643-10ab182431a1","AGENTS.md","3fda9822-7dba-11f1-a60b-1607ee4eb77e",159,["D",1783879967584],4,[200],"7529ead0-4fee-4931-9ae8-38a0877f8a58",".vtignore","365e30b4-7dac-11f1-904e-1607ee4eb77e",40,["D",1783831402416],".git\n.vscode\n.cursor\n.claude\n.DS_Store\nnode_modules\nvendor",[207],"b853cae8-c7ca-4cb6-bd52-5120745a171a","src","59dbb9bc-7e06-11f1-ae23-1607ee4eb77e",68,["D",1783870116679],"directory",[214],"a3f979cb-9774-4c49-a797-f5bd4c8469df","docs","3f266b0e-7dba-11f1-8f0a-1607ee4eb77e",47,["D",1783837430189],[221],"pulls","branches","forks","envVars",{"_233":61,"_235":196},"connections",{"_233":196,"_234":196},"count","unfilledCount","emptyCount",{"_43":220,"_32":221,"_30":222,"_142":-5,"_41":42,"_40":223,"_144":171,"_38":577,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_283":578,"_27":579},{"_43":572,"_32":539,"_30":533,"_142":222,"_41":42,"_40":573,"_144":171,"_38":574,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_283":575,"_27":576},{"_43":564,"_32":565,"_30":566,"_142":533,"_41":42,"_40":567,"_144":171,"_38":568,"_13":61,"_34":20,"_35":569,"_24":25,"_149":-5,"_283":570,"_27":571},{"_43":556,"_32":557,"_30":558,"_142":533,"_41":42,"_40":559,"_144":171,"_38":560,"_13":61,"_34":20,"_35":561,"_24":25,"_149":-5,"_283":562,"_27":563},{"_43":548,"_32":549,"_30":550,"_142":533,"_41":42,"_40":551,"_144":171,"_38":552,"_13":61,"_34":20,"_35":553,"_24":25,"_149":-5,"_283":554,"_27":555},{"_43":540,"_32":541,"_30":542,"_142":533,"_41":42,"_40":543,"_144":171,"_38":544,"_13":61,"_34":20,"_35":545,"_24":25,"_149":-5,"_283":546,"_27":547},{"_43":530,"_32":531,"_30":532,"_142":533,"_41":42,"_40":534,"_144":171,"_38":535,"_13":196,"_34":20,"_35":536,"_24":25,"_149":-5,"_283":537,"_27":538},{"_43":525,"_32":508,"_30":502,"_142":222,"_41":42,"_40":526,"_144":171,"_38":527,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_283":528,"_27":529},{"_43":517,"_32":518,"_30":519,"_142":502,"_41":42,"_40":520,"_144":171,"_38":521,"_13":61,"_34":20,"_35":522,"_24":25,"_149":-5,"_283":523,"_27":524},{"_43":509,"_32":510,"_30":511,"_142":502,"_41":42,"_40":512,"_144":171,"_38":513,"_13":61,"_34":20,"_35":514,"_24":25,"_149":-5,"_283":515,"_27":516},{"_43":499,"_32":500,"_30":501,"_142":502,"_41":42,"_40":503,"_144":171,"_38":504,"_13":61,"_34":20,"_35":505,"_24":25,"_149":-5,"_283":506,"_27":507},{"_43":494,"_32":485,"_30":479,"_142":222,"_41":42,"_40":495,"_144":171,"_38":496,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_283":497,"_27":498},{"_43":486,"_32":487,"_30":488,"_142":479,"_41":42,"_40":489,"_144":171,"_38":490,"_13":196,"_34":20,"_35":491,"_24":25,"_149":-5,"_283":492,"_27":493},{"_43":476,"_32":477,"_30":478,"_142":479,"_41":42,"_40":480,"_144":171,"_38":481,"_13":196,"_34":20,"_35":482,"_24":25,"_149":-5,"_283":483,"_27":484},{"_43":471,"_32":336,"_30":394,"_142":222,"_41":42,"_40":472,"_144":171,"_38":473,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_283":474,"_27":475},{"_43":466,"_32":459,"_30":453,"_142":394,"_41":42,"_40":467,"_144":171,"_38":468,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_283":469,"_27":470},{"_43":460,"_32":336,"_30":461,"_142":453,"_41":42,"_40":462,"_144":171,"_38":463,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_283":464,"_27":465},{"_43":451,"_32":33,"_30":452,"_142":453,"_41":42,"_40":454,"_144":171,"_38":455,"_13":376,"_34":20,"_35":456,"_24":25,"_149":-5,"_283":457,"_27":458},{"_43":446,"_32":407,"_30":401,"_142":394,"_41":42,"_40":447,"_144":171,"_38":448,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_283":449,"_27":450},{"_43":441,"_32":336,"_30":411,"_142":401,"_41":42,"_40":442,"_144":171,"_38":443,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_283":444,"_27":445},{"_43":433,"_32":434,"_30":435,"_142":411,"_41":42,"_40":436,"_144":171,"_38":437,"_13":188,"_34":20,"_35":438,"_24":25,"_149":-5,"_283":439,"_27":440},{"_43":425,"_32":426,"_30":427,"_142":411,"_41":42,"_40":428,"_144":171,"_38":429,"_13":188,"_34":20,"_35":430,"_24":25,"_149":-5,"_283":431,"_27":432},{"_43":417,"_32":418,"_30":419,"_142":411,"_41":42,"_40":420,"_144":171,"_38":421,"_13":188,"_34":20,"_35":422,"_24":25,"_149":-5,"_283":423,"_27":424},{"_43":408,"_32":409,"_30":410,"_142":411,"_41":42,"_40":412,"_144":171,"_38":413,"_13":156,"_34":20,"_35":414,"_24":25,"_149":-5,"_283":415,"_27":416},{"_43":399,"_32":33,"_30":400,"_142":401,"_41":42,"_40":402,"_144":171,"_38":403,"_13":204,"_34":20,"_35":404,"_24":25,"_149":-5,"_283":405,"_27":406},{"_43":393,"_32":337,"_30":332,"_142":394,"_41":42,"_40":395,"_144":171,"_38":396,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_283":397,"_27":398},{"_43":388,"_32":336,"_30":341,"_142":332,"_41":42,"_40":389,"_144":171,"_38":390,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_283":391,"_27":392},{"_43":380,"_32":381,"_30":382,"_142":341,"_41":42,"_40":383,"_144":171,"_38":384,"_13":376,"_34":20,"_35":385,"_24":25,"_149":-5,"_283":386,"_27":387},{"_43":371,"_32":372,"_30":373,"_142":341,"_41":42,"_40":374,"_144":171,"_38":375,"_13":376,"_34":20,"_35":377,"_24":25,"_149":-5,"_283":378,"_27":379},{"_43":363,"_32":364,"_30":365,"_142":341,"_41":42,"_40":366,"_144":171,"_38":367,"_13":204,"_34":20,"_35":368,"_24":25,"_149":-5,"_283":369,"_27":370},{"_43":355,"_32":356,"_30":357,"_142":341,"_41":42,"_40":358,"_144":25,"_38":359,"_13":204,"_34":20,"_35":360,"_24":25,"_149":-5,"_283":361,"_27":362},{"_43":347,"_32":348,"_30":349,"_142":341,"_41":42,"_40":350,"_144":171,"_38":351,"_13":204,"_34":20,"_35":352,"_24":25,"_149":-5,"_283":353,"_27":354},{"_43":338,"_32":339,"_30":340,"_142":341,"_41":42,"_40":342,"_144":171,"_38":343,"_13":188,"_34":20,"_35":344,"_24":25,"_149":-5,"_283":345,"_27":346},{"_43":331,"_32":33,"_30":31,"_142":332,"_41":42,"_40":14,"_144":171,"_38":333,"_13":156,"_34":20,"_35":37,"_24":25,"_149":-5,"_283":334,"_27":335},{"_43":213,"_32":214,"_30":215,"_142":-5,"_41":42,"_40":216,"_144":171,"_38":328,"_13":196,"_34":218,"_35":-5,"_24":25,"_149":-5,"_283":329,"_27":330},{"_43":319,"_32":320,"_30":321,"_142":215,"_41":42,"_40":322,"_144":25,"_38":323,"_13":324,"_34":147,"_35":325,"_24":25,"_149":-5,"_283":326,"_27":327},{"_43":310,"_32":311,"_30":312,"_142":215,"_41":42,"_40":313,"_144":25,"_38":314,"_13":315,"_34":147,"_35":316,"_24":25,"_149":-5,"_283":317,"_27":318},{"_43":206,"_32":207,"_30":208,"_142":-5,"_41":42,"_40":209,"_144":171,"_38":307,"_13":196,"_34":20,"_35":211,"_24":25,"_149":-5,"_283":308,"_27":309},{"_43":199,"_32":200,"_30":201,"_142":-5,"_41":42,"_40":202,"_144":171,"_38":304,"_13":204,"_34":20,"_35":189,"_24":25,"_149":-5,"_283":305,"_27":306},{"_43":191,"_32":192,"_30":193,"_142":-5,"_41":42,"_40":194,"_144":171,"_38":301,"_13":196,"_34":20,"_35":197,"_24":25,"_149":-5,"_283":302,"_27":303},{"_43":183,"_32":184,"_30":185,"_142":-5,"_41":42,"_40":186,"_144":171,"_38":298,"_13":188,"_34":20,"_35":189,"_24":25,"_149":-5,"_283":299,"_27":300},{"_43":175,"_32":176,"_30":177,"_142":-5,"_41":42,"_40":178,"_144":25,"_38":295,"_13":180,"_34":20,"_35":181,"_24":25,"_149":-5,"_283":296,"_27":297},{"_43":167,"_32":168,"_30":169,"_142":-5,"_41":42,"_40":170,"_144":171,"_38":292,"_13":61,"_34":147,"_35":173,"_24":25,"_149":-5,"_283":293,"_27":294},{"_43":159,"_32":160,"_30":161,"_142":-5,"_41":42,"_40":162,"_144":25,"_38":289,"_13":164,"_34":20,"_35":165,"_24":25,"_149":-5,"_283":290,"_27":291},{"_43":151,"_32":152,"_30":153,"_142":-5,"_41":42,"_40":154,"_144":25,"_38":286,"_13":156,"_34":147,"_35":157,"_24":25,"_149":-5,"_283":287,"_27":288},{"_43":139,"_32":140,"_30":141,"_142":-5,"_41":42,"_40":143,"_144":25,"_38":282,"_13":146,"_34":147,"_35":148,"_24":25,"_149":-5,"_283":284,"_27":285},["D",1783923547434],"children",[],[140],["D",1783874292383],[],[152],["D",1783880366517],[],[160],["D",1783881460722],[],[168],["D",1783897351819],[],[176],["D",1783879967783],[],[184],["D",1783882245610],[],[192],["D",1783879967584],[],[200],["D",1783831402416],[],[207],"7b42db58-bc29-485e-86b8-6f00c077c42e","stash_test.ts","5a4ea65c-7e06-11f1-8f58-1607ee4eb77e",199,["D",1783897351987],8,"import { DatabaseSync } from \"node:sqlite\";\nimport type { Client, InStatement } from \"npm:@libsql/client@0.17.2\";\nimport { createStash, type SqliteClient, type SqlStatement } from \"./stash.ts\";\n\ntype Assert = T;\ntype IsAssignable = [From] extends [To] ? true : false;\ntype LibsqlClientMatchesSeam = Assert<\n IsAssignable\n>;\ntype TownstashStatementMatchesLibsql = Assert<\n IsAssignable\n>;\n\ntype NodeSqliteNamedArgs = Record<\n string,\n string | number | bigint | null | Uint8Array\n>;\n\nfunction sqliteAdapter(database: DatabaseSync): SqliteClient {\n const execute = (statement: string | SqlStatement) => {\n const { sql, args = [] } = typeof statement === \"string\"\n ? { sql: statement, args: [] }\n : statement;\n const prepared = database.prepare(sql);\n if (/^\\s*SELECT\\b/i.test(sql) || /\\bRETURNING\\b/i.test(sql)) {\n const rows = Array.isArray(args)\n ? prepared.all(...(args as Parameters))\n : prepared.all(args as NodeSqliteNamedArgs);\n return Promise.resolve({\n rows: rows as Record[],\n });\n }\n if (Array.isArray(args)) {\n prepared.run(...(args as Parameters));\n } else {\n prepared.run(args as NodeSqliteNamedArgs);\n }\n return Promise.resolve({ rows: [] });\n };\n\n return {\n execute,\n async batch(statements) {\n database.exec(\"BEGIN\");\n try {\n for (const statement of statements) await execute(statement);\n database.exec(\"COMMIT\");\n } catch (error) {\n database.exec(\"ROLLBACK\");\n throw error;\n }\n },\n };\n}\n\nfunction assertEquals(actual: unknown, expected: unknown): void {\n if (JSON.stringify(actual) !== JSON.stringify(expected)) {\n throw new Error(\n `Expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`,\n );\n }\n}\n\nfunction testClient() {\n const database = new DatabaseSync(\":memory:\");\n return { database, stash: createStash(sqliteAdapter(database)) };\n}\n\nfunction controlledClient(start = 1_000) {\n const database = new DatabaseSync(\":memory:\");\n let now = start;\n const stash = createStash(sqliteAdapter(database), { now: () => now });\n return {\n database,\n stash,\n setNow(value: number) {\n now = value;\n },\n };\n}\n\nDeno.test(\"representative v1 workflow uses the public client on real SQLite\", async () => {\n const { stash } = controlledClient();\n const sessions = stash.withPrefix(\"release:\");\n\n assertEquals(\n await sessions.set(\"user:123\", \"Ada\", { nx: true, ttlMs: 60_000 }),\n true,\n );\n assertEquals(await sessions.get(\"user:123\"), \"Ada\");\n assertEquals(await stash.get(\"release:user:123\"), \"Ada\");\n assertEquals(await sessions.exists(\"user:123\"), true);\n assertEquals(await sessions.type(\"user:123\"), \"string\");\n assertEquals(await sessions.ttl(\"user:123\"), 60_000);\n\n assertEquals(await sessions.setJSON(\"profile:123\", { plan: \"pro\" }), true);\n assertEquals(await sessions.getJSON(\"profile:123\"), { plan: \"pro\" });\n\n assertEquals(await sessions.incr(\"visits\", 2), 2);\n assertEquals(await sessions.decr(\"visits\", -1), 3);\n assertEquals(await sessions.persist(\"visits\"), false);\n assertEquals(await sessions.del(\"user:123\", \"profile:123\", \"visits\"), 3);\n assertEquals(await sessions.exists(\"user:123\"), false);\n});\n\nDeno.test(\"text values round-trip and missing values are undefined\", async () => {\n const { stash } = testClient();\n assertEquals(await stash.get(\"missing\"), undefined);\n assertEquals(await stash.set(\"greeting\", \"Hello, 🌎\"), true);\n assertEquals(await stash.get(\"greeting\"), \"Hello, 🌎\");\n});\n\nDeno.test(\"bytes round-trip without UTF-8 conversion or shared mutation\", async () => {\n const { stash } = testClient();\n const input = new Uint8Array([0, 255, 128, 1]);\n assertEquals(await stash.getBytes(\"missing\"), undefined);\n await stash.setBytes(\"binary\", input);\n input[0] = 99;\n const output = await stash.getBytes(\"binary\");\n assertEquals(Array.from(output ?? []), [0, 255, 128, 1]);\n if (output) output[1] = 42;\n assertEquals(\n Array.from((await stash.getBytes(\"binary\")) ?? []),\n [0, 255, 128, 1],\n );\n});\n\nDeno.test(\"JSON helpers round-trip values and preserve write options\", async () => {\n const { stash, setNow } = controlledClient();\n\n assertEquals(await stash.getJSON(\"missing\"), undefined);\n assertEquals(\n await stash.setJSON(\n \"profile\",\n { name: \"Ada\", roles: [\"admin\", \"author\"] },\n { nx: true, ttlMs: 100 },\n ),\n true,\n );\n assertEquals(\n await stash.setJSON(\"profile\", { name: \"Grace\" }, { nx: true }),\n false,\n );\n assertEquals(await stash.getJSON(\"profile\"), {\n name: \"Ada\",\n roles: [\"admin\", \"author\"],\n });\n assertEquals(await stash.ttl(\"profile\"), 100);\n\n setNow(1_100);\n assertEquals(await stash.getJSON(\"profile\"), undefined);\n assertEquals(\n await stash.setJSON(\"profile\", { name: \"Grace\" }, { xx: true }),\n false,\n );\n\n await stash.set(\"malformed\", \"not JSON\");\n try {\n await stash.getJSON(\"malformed\");\n throw new Error(\"Expected malformed JSON to fail\");\n } catch (error) {\n if (!(error instanceof SyntaxError)) throw error;\n }\n assertEquals(await stash.get(\"malformed\"), \"not JSON\");\n\n try {\n await stash.setJSON(\"undefined\", undefined);\n throw new Error(\"Expected undefined JSON to fail\");\n } catch (error) {\n if (!(error instanceof TypeError)) throw error;\n }\n assertEquals(await stash.exists(\"undefined\"), false);\n});\n\nDeno.test(\"prefixed clients use the flat keyspace and compose in call order\", async () => {\n const { stash } = testClient();\n const tenant = stash.withPrefix(\"tenant:\");\n\n await tenant.setJSON(\"profile\", { plan: \"pro\" });\n assertEquals(await stash.get(\"tenant:profile\"), '{\"plan\":\"pro\"}');\n assertEquals(await tenant.getJSON(\"profile\"), { plan: \"pro\" });\n assertEquals(await stash.get(\"profile\"), undefined);\n\n await tenant.set(\"one\", \"1\");\n await stash.set(\"tenant:two\", \"2\");\n assertEquals(await tenant.exists(\"one\"), true);\n assertEquals(await tenant.type(\"two\"), \"string\");\n assertEquals(await tenant.del(\"one\", \"two\", \"missing\"), 2);\n assertEquals(await stash.exists(\"tenant:one\"), false);\n assertEquals(await stash.exists(\"tenant:two\"), false);\n\n const nested = tenant.withPrefix(\"v1:\");\n await nested.set(\"key\", \"value\");\n assertEquals(await stash.get(\"tenant:v1:key\"), \"value\");\n assertEquals(await stash.get(\"v1:key\"), undefined);\n});\n\nDeno.test(\"prefixed clients forward lifecycle, bytes, and counter commands\", async () => {\n const { stash, setNow } = controlledClient();\n const prefixed = stash.withPrefix(\"app:\");\n\n await prefixed.setBytes(\"binary\", new Uint8Array([1, 2]), { ttlMs: 100 });\n assertEquals(Array.from((await prefixed.getBytes(\"binary\")) ?? []), [1, 2]);\n assertEquals(await prefixed.ttl(\"binary\"), 100);\n assertEquals(await prefixed.expire(\"binary\", 200), true);\n assertEquals(await stash.ttl(\"app:binary\"), 200);\n assertEquals(await prefixed.persist(\"binary\"), true);\n assertEquals(await prefixed.ttl(\"binary\"), -1);\n\n assertEquals(await prefixed.incr(\"counter\", 2), 2);\n assertEquals(await prefixed.decr(\"counter\"), 1);\n assertEquals(await prefixed.expireAt(\"counter\", new Date(2_000)), true);\n assertEquals(await stash.ttl(\"app:counter\"), 1_000);\n\n await prefixed.set(\"expired\", \"value\", { ttlMs: 1 });\n setNow(1_001);\n assertEquals(await prefixed.cleanup(), 1);\n assertEquals(await stash.exists(\"app:expired\"), false);\n});\n\nDeno.test(\"initialization is repeatable and preserves stored data\", async () => {\n const database = new DatabaseSync(\":memory:\");\n const adapter = sqliteAdapter(database);\n const first = createStash(adapter);\n await first.set(\"key\", \"value\");\n const second = createStash(adapter);\n assertEquals(await second.get(\"key\"), \"value\");\n});\n\nDeno.test(\"replacement clears expiration unless keepTtl is requested\", async () => {\n const { database, stash } = controlledClient();\n await stash.set(\"key\", \"first\");\n database\n .prepare(\"UPDATE stash_keys SET expires_at = 1_100 WHERE key = ?\")\n .run(\"key\");\n await stash.set(\"key\", \"second\", { keepTtl: true });\n assertEquals(\n (\n database\n .prepare(\"SELECT expires_at FROM stash_keys WHERE key = ?\")\n .get(\"key\") as { expires_at: number }\n ).expires_at,\n 1_100,\n );\n await stash.set(\"key\", \"third\");\n assertEquals(\n (\n database\n .prepare(\"SELECT expires_at FROM stash_keys WHERE key = ?\")\n .get(\"key\") as { expires_at: number | null }\n ).expires_at,\n null,\n );\n assertEquals(await stash.get(\"key\"), \"third\");\n});\n\nDeno.test(\"conditional set reports whether it wrote and preserves failed values\", async () => {\n const { stash } = testClient();\n\n assertEquals(await stash.set(\"missing\", \"claimed\", { nx: true }), true);\n assertEquals(await stash.set(\"missing\", \"replaced\", { nx: true }), false);\n assertEquals(await stash.get(\"missing\"), \"claimed\");\n\n assertEquals(await stash.set(\"missing\", \"updated\", { xx: true }), true);\n assertEquals(await stash.get(\"missing\"), \"updated\");\n assertEquals(await stash.set(\"other\", \"created\", { xx: true }), false);\n assertEquals(await stash.get(\"other\"), undefined);\n});\n\nDeno.test(\"set supports relative and absolute expiration\", async () => {\n const { stash, setNow } = controlledClient();\n\n assertEquals(await stash.set(\"relative\", \"value\", { ttlMs: 5_000 }), true);\n assertEquals(await stash.ttl(\"relative\"), 5_000);\n assertEquals(await stash.exists(\"relative\"), true);\n assertEquals(await stash.type(\"relative\"), \"string\");\n\n setNow(5_999);\n assertEquals(await stash.ttl(\"relative\"), 1);\n setNow(6_000);\n assertEquals(await stash.get(\"relative\"), undefined);\n assertEquals(await stash.exists(\"relative\"), false);\n assertEquals(await stash.type(\"relative\"), \"none\");\n assertEquals(await stash.ttl(\"relative\"), undefined);\n\n assertEquals(\n await stash.set(\"absolute\", \"value\", { expiresAt: new Date(8_000) }),\n true,\n );\n assertEquals(await stash.ttl(\"absolute\"), 2_000);\n});\n\nDeno.test(\"expiration validation happens before database execution\", async () => {\n const database = new DatabaseSync(\":memory:\");\n const base = sqliteAdapter(database);\n let calls = 0;\n const stash = createStash(\n {\n execute(statement) {\n calls += 1;\n return base.execute(statement);\n },\n batch(statements) {\n calls += 1;\n return base.batch(statements);\n },\n },\n { now: () => 1_000 },\n );\n\n try {\n await stash.set(\"key\", \"value\", {\n ttlMs: 1_000,\n expiresAt: new Date(2_000),\n });\n throw new Error(\"Expected incompatible expiration options to fail\");\n } catch (error) {\n if (!(error instanceof TypeError)) throw error;\n }\n assertEquals(calls, 0);\n});\n\nDeno.test(\"relative expiration starts after schema initialization\", async () => {\n const database = new DatabaseSync(\":memory:\");\n const base = sqliteAdapter(database);\n let now = 1_000;\n const stash = createStash(\n {\n execute: base.execute,\n async batch(statements) {\n now += 500;\n return await base.batch(statements);\n },\n },\n { now: () => now },\n );\n\n await stash.set(\"delayed\", \"value\", { ttlMs: 1_000 });\n assertEquals(await stash.ttl(\"delayed\"), 1_000);\n});\n\nDeno.test(\"expire, persist, and ttl manage a visible key\", async () => {\n const { stash, setNow } = controlledClient();\n\n await stash.set(\"key\", \"value\");\n assertEquals(await stash.ttl(\"key\"), -1);\n assertEquals(await stash.expire(\"key\", 2_000), true);\n assertEquals(await stash.ttl(\"key\"), 2_000);\n\n setNow(2_000);\n assertEquals(await stash.persist(\"key\"), true);\n assertEquals(await stash.ttl(\"key\"), -1);\n assertEquals(await stash.persist(\"key\"), false);\n\n assertEquals(await stash.expire(\"missing\", 1_000), false);\n assertEquals(await stash.expireAt(\"missing\", new Date(4_000)), false);\n});\n\nDeno.test(\"expired keys are absent from lifecycle commands\", async () => {\n const { stash, setNow } = controlledClient();\n\n await stash.set(\"expired\", \"value\", { ttlMs: 10 });\n setNow(1_010);\n assertEquals(await stash.expire(\"expired\", 1_000), false);\n assertEquals(await stash.expireAt(\"expired\", new Date(5_000)), false);\n assertEquals(await stash.persist(\"expired\"), false);\n assertEquals(await stash.del(\"expired\"), 0);\n assertEquals(await stash.ttl(\"expired\"), undefined);\n assertEquals(await stash.cleanup(), 1);\n assertEquals(await stash.cleanup(), 0);\n});\n\nDeno.test(\"keepTtl preserves only a visible expiration\", async () => {\n const { stash, setNow } = controlledClient();\n\n await stash.set(\"visible\", \"first\", { ttlMs: 100 });\n setNow(1_050);\n assertEquals(await stash.set(\"visible\", \"second\", { keepTtl: true }), true);\n assertEquals(await stash.ttl(\"visible\"), 50);\n\n setNow(1_100);\n assertEquals(await stash.set(\"visible\", \"third\", { keepTtl: true }), true);\n assertEquals(await stash.ttl(\"visible\"), -1);\n});\n\nDeno.test(\"del counts distinct visible keys and cleanup only reclaims expired rows\", async () => {\n const { database, stash, setNow } = controlledClient();\n\n await stash.set(\"one\", \"1\");\n await stash.set(\"two\", \"2\", { ttlMs: 10 });\n await stash.set(\"three\", \"3\");\n setNow(1_010);\n\n assertEquals(await stash.del(\"one\", \"one\", \"two\", \"missing\"), 1);\n assertEquals(await stash.get(\"two\"), undefined);\n assertEquals(await stash.cleanup(), 1);\n assertEquals(\n (\n database.prepare(\"SELECT COUNT(*) AS count FROM stash_keys\").get() as {\n count: number;\n }\n ).count,\n 1,\n );\n assertEquals(await stash.get(\"three\"), \"3\");\n});\n\nDeno.test(\"conditional set works for byte values and expired keys\", async () => {\n const { database, stash } = testClient();\n await stash.setBytes(\"binary\", new Uint8Array([1, 2]), { nx: true });\n assertEquals(\n await stash.setBytes(\"binary\", new Uint8Array([3, 4]), { nx: true }),\n false,\n );\n assertEquals(Array.from((await stash.getBytes(\"binary\")) ?? []), [1, 2]);\n\n database\n .prepare(\"UPDATE stash_keys SET expires_at = ? WHERE key = ?\")\n .run(Date.now() - 1, \"binary\");\n assertEquals(\n await stash.setBytes(\"binary\", new Uint8Array([3, 4]), { nx: true }),\n true,\n );\n assertEquals(Array.from((await stash.getBytes(\"binary\")) ?? []), [3, 4]);\n assertEquals(\n await stash.setBytes(\"binary\", new Uint8Array([5, 6]), { xx: true }),\n true,\n );\n assertEquals(Array.from((await stash.getBytes(\"binary\")) ?? []), [5, 6]);\n});\n\nDeno.test(\"incompatible conditions fail before database execution\", async () => {\n const database = new DatabaseSync(\":memory:\");\n const base = sqliteAdapter(database);\n let calls = 0;\n const stash = createStash({\n execute(statement) {\n calls += 1;\n return base.execute(statement);\n },\n batch(statements) {\n calls += 1;\n return base.batch(statements);\n },\n });\n\n try {\n await stash.set(\"key\", \"value\", { nx: true, xx: true });\n throw new Error(\"Expected incompatible set conditions to fail\");\n } catch (error) {\n if (!(error instanceof TypeError)) throw error;\n }\n assertEquals(calls, 0);\n});\n\nDeno.test(\"competing nx writes have exactly one winner on the real adapter\", async () => {\n const { stash } = testClient();\n const attempts = await Promise.all(\n Array.from(\n { length: 32 },\n (_, index) => stash.set(\"lock\", `winner-${index}`, { nx: true }),\n ),\n );\n\n assertEquals(attempts.filter(Boolean).length, 1);\n const winner = await stash.get(\"lock\");\n if (!winner?.startsWith(\"winner-\")) {\n throw new Error(`Expected a competing write to win, got ${winner}`);\n }\n});\n\nDeno.test(\"counters support signed increments and decrements\", async () => {\n const { stash } = testClient();\n\n assertEquals(await stash.incr(\"counter\"), 1);\n assertEquals(await stash.incr(\"counter\", 4), 5);\n assertEquals(await stash.decr(\"counter\"), 4);\n assertEquals(await stash.decr(\"counter\", -3), 7);\n assertEquals(await stash.get(\"counter\"), \"7\");\n});\n\nDeno.test(\"counters preserve visible TTLs and reset expired values from zero\", async () => {\n const { stash, setNow } = controlledClient();\n\n await stash.set(\"counter\", \"5\", { ttlMs: 100 });\n setNow(1_050);\n assertEquals(await stash.incr(\"counter\"), 6);\n assertEquals(await stash.ttl(\"counter\"), 50);\n\n setNow(1_100);\n assertEquals(await stash.incr(\"counter\"), 1);\n assertEquals(await stash.get(\"counter\"), \"1\");\n assertEquals(await stash.ttl(\"counter\"), -1);\n});\n\nDeno.test(\"invalid counter state and overflow do not mutate values\", async () => {\n const { stash } = testClient();\n\n await stash.set(\"non-canonical\", \"01\");\n try {\n await stash.incr(\"non-canonical\");\n throw new Error(\"Expected non-canonical counter state to fail\");\n } catch (error) {\n if (!(error instanceof TypeError)) throw error;\n }\n assertEquals(await stash.get(\"non-canonical\"), \"01\");\n\n await stash.set(\"maximum-boundary\", \"9223372036854775806\");\n await stash.incr(\"maximum-boundary\");\n assertEquals(await stash.get(\"maximum-boundary\"), \"9223372036854775807\");\n\n await stash.set(\"maximum\", \"9223372036854775807\");\n try {\n await stash.incr(\"maximum\");\n throw new Error(\"Expected signed 64-bit overflow to fail\");\n } catch (error) {\n if (!(error instanceof RangeError)) throw error;\n }\n assertEquals(await stash.get(\"maximum\"), \"9223372036854775807\");\n\n await stash.set(\"minimum-boundary\", \"-9223372036854775807\");\n await stash.decr(\"minimum-boundary\");\n assertEquals(await stash.get(\"minimum-boundary\"), \"-9223372036854775808\");\n\n await stash.set(\"minimum\", \"-9223372036854775808\");\n try {\n await stash.decr(\"minimum\");\n throw new Error(\"Expected signed 64-bit underflow to fail\");\n } catch (error) {\n if (!(error instanceof RangeError)) throw error;\n }\n assertEquals(await stash.get(\"minimum\"), \"-9223372036854775808\");\n});\n\nDeno.test(\"counter amounts and wrong types are rejected without mutation\", async () => {\n const { database, stash } = testClient();\n\n await stash.set(\"amount\", \"4\");\n try {\n await stash.incr(\"amount\", 1.5);\n throw new Error(\"Expected a non-integer counter amount to fail\");\n } catch (error) {\n if (!(error instanceof TypeError)) throw error;\n }\n assertEquals(await stash.get(\"amount\"), \"4\");\n\n database\n .prepare(\"UPDATE stash_keys SET type = ? WHERE key = ?\")\n .run(\"hash\", \"amount\");\n try {\n await stash.incr(\"amount\");\n throw new Error(\"Expected a wrong-type counter value to fail\");\n } catch (error) {\n if (!(error instanceof TypeError)) throw error;\n }\n try {\n await stash.getBytes(\"amount\");\n throw new Error(\"Expected a wrong-type read to fail\");\n } catch (error) {\n if (!(error instanceof TypeError)) throw error;\n }\n database\n .prepare(\"UPDATE stash_keys SET type = ? WHERE key = ?\")\n .run(\"string\", \"amount\");\n assertEquals(await stash.get(\"amount\"), \"4\");\n});\n\nDeno.test(\"overlapping increments lose no updates on the real adapter\", async () => {\n const { stash } = testClient();\n const results = await Promise.all(\n Array.from({ length: 32 }, () => stash.incr(\"counter\")),\n );\n\n assertEquals(results.length, 32);\n assertEquals(await stash.get(\"counter\"), \"32\");\n});\n",[],[214,311],"b28a178c-d72c-444e-8d0e-ded6bb0e5c14","stash.ts","5a22163c-7e06-11f1-8f03-1607ee4eb77e",211,["D",1783900267874],19,"export type StashValue = string | Uint8Array;\n\nexport interface SetOptions {\n /** Expire the key this many milliseconds after command execution begins. */\n ttlMs?: number;\n /** Expire the key at this absolute instant. */\n expiresAt?: Date;\n /** Set only when the key is absent or expired. */\n nx?: boolean;\n /** Set only when the key exists and has not expired. */\n xx?: boolean;\n /** Preserve an existing key's expiration when replacing its value. */\n keepTtl?: boolean;\n}\n\nexport interface Stash {\n get(key: string): Promise;\n getBytes(key: string): Promise;\n getJSON(key: string): Promise;\n set(key: string, value: StashValue, options?: SetOptions): Promise;\n setBytes(\n key: string,\n value: Uint8Array,\n options?: SetOptions,\n ): Promise;\n setJSON(key: string, value: T, options?: SetOptions): Promise;\n del(...keys: string[]): Promise;\n exists(key: string): Promise;\n type(key: string): Promise<\"string\" | \"none\">;\n expire(key: string, ttlMs: number): Promise;\n expireAt(key: string, expiresAt: Date): Promise;\n persist(key: string): Promise;\n /** Returns remaining milliseconds, -1 for persistent keys, or undefined when absent. */\n ttl(key: string): Promise;\n /** Removes expired rows and returns the number of rows reclaimed. */\n cleanup(): Promise;\n incr(key: string, by?: number): Promise;\n decr(key: string, by?: number): Promise;\n withPrefix(prefix: string): Stash;\n}\n\nexport interface StashOptions {\n /** Internal test seam for deterministic expiration behavior. */\n now?: () => number;\n}\n\nexport interface SqlStatement {\n sql: string;\n args?: SqlValue[] | Record;\n}\n\nexport type SqlValue = string | number | bigint | boolean | null | Uint8Array;\n\nexport interface SqlResult {\n rows: Record[];\n}\n\nexport interface SqliteClient {\n execute(statement: string | SqlStatement): Promise;\n batch(statements: SqlStatement[]): Promise;\n}\n\nfunction defineStatement(sql: string) {\n return (\n args:\n & B\n & Record\n & Record, never>,\n ): SqlStatement => ({\n sql,\n args: args as Record,\n });\n}\n\nconst schemaStatements: SqlStatement[] = [\n {\n sql: `CREATE TABLE IF NOT EXISTS\n stash_keys (\n key TEXT PRIMARY KEY,\n type TEXT NOT NULL,\n value BLOB,\n expires_at INTEGER,\n version INTEGER NOT NULL DEFAULT 1\n )`,\n },\n {\n sql:\n `CREATE INDEX IF NOT EXISTS stash_keys_expiration ON stash_keys (expires_at)\nWHERE\n expires_at IS NOT NULL`,\n },\n];\n\ninterface SelectValueArgs {\n key: string;\n now: number;\n}\n\nconst selectValue = defineStatement(`SELECT\n TYPE,\n value\nFROM\n stash_keys\nWHERE\n KEY = :key\n AND (\n expires_at IS NULL\n OR expires_at > :now\n )`);\n\ninterface UpsertArgs {\n key: string;\n value: Uint8Array;\n expiresAt: number | null;\n mode: 0 | 1 | 2;\n now: number;\n keepTtl: 0 | 1;\n}\n\nconst upsertValue = defineStatement(`INSERT INTO\n stash_keys (KEY, TYPE, value, expires_at)\nSELECT\n :key,\n 'string',\n :value,\n :expiresAt\nWHERE\n :mode <> 2\n OR EXISTS (\n SELECT\n 1\n FROM\n stash_keys\n WHERE\n KEY = :key\n AND (\n expires_at IS NULL\n OR expires_at > :now\n )\n ) ON CONFLICT (KEY) DO\nUPDATE\nSET\n TYPE = 'string',\n value = excluded.value,\n expires_at = CASE\n WHEN :keepTtl\n AND (\n stash_keys.expires_at IS NULL\n OR stash_keys.expires_at > :now\n ) THEN stash_keys.expires_at\n ELSE excluded.expires_at\n END,\n version = stash_keys.version + 1\nWHERE\n :mode = 0\n OR (\n :mode = 1\n AND stash_keys.expires_at IS NOT NULL\n AND stash_keys.expires_at <= :now\n )\n OR (\n :mode = 2\n AND (\n stash_keys.expires_at IS NULL\n OR stash_keys.expires_at > :now\n )\n ) RETURNING 1 AS written\n`);\n\nconst visibleExpiration = `(expires_at IS NULL OR expires_at > :now)`;\n\ninterface IncrementArgs {\n key: string;\n delta: number;\n now: number;\n}\n\nconst incrementValue = defineStatement(`INSERT INTO\n stash_keys (key, type, value, expires_at)\nVALUES\n (\n :key,\n 'string',\n CAST(CAST(:delta AS INTEGER) AS BLOB),\n NULL\n ) ON CONFLICT (KEY) DO\nUPDATE\nSET\n TYPE = 'string',\n value = CASE\n WHEN stash_keys.expires_at IS NULL\n OR stash_keys.expires_at > :now THEN CAST(\n CAST(CAST(stash_keys.value AS TEXT) AS INTEGER) + CAST(excluded.value AS INTEGER) AS BLOB\n )\n ELSE excluded.value\n END,\n expires_at = CASE\n WHEN stash_keys.expires_at IS NULL\n OR stash_keys.expires_at > :now THEN stash_keys.expires_at\n ELSE NULL\n END,\n version = stash_keys.version + 1\nWHERE\n (\n stash_keys.expires_at IS NOT NULL\n AND stash_keys.expires_at <= :now\n )\n OR (\n (\n stash_keys.expires_at IS NULL\n OR stash_keys.expires_at > :now\n )\n AND stash_keys.type = 'string'\n AND CAST(stash_keys.value AS TEXT) = CAST(\n CAST(CAST(stash_keys.value AS TEXT) AS INTEGER) AS TEXT\n )\n AND (\n CAST(excluded.value AS INTEGER) = 0\n OR (\n CAST(excluded.value AS INTEGER) > 0\n AND CAST(CAST(stash_keys.value AS TEXT) AS INTEGER) <= CAST('9223372036854775807' AS INTEGER) - CAST(excluded.value AS INTEGER)\n )\n OR (\n CAST(excluded.value AS INTEGER) < 0\n AND CAST(CAST(stash_keys.value AS TEXT) AS INTEGER) >= CAST('-9223372036854775808' AS INTEGER) - CAST(excluded.value AS INTEGER)\n )\n )\n ) RETURNING CAST(value AS TEXT) AS result`);\n\ninterface CounterStateArgs {\n key: string;\n now: number;\n}\n\nconst counterState = defineStatement(`SELECT\n TYPE,\n CAST(value AS TEXT) AS text_value,\n CAST(CAST(CAST(value AS TEXT) AS INTEGER) AS TEXT) AS canonical_value\nFROM\n stash_keys\nWHERE\n KEY = :key\n AND ${visibleExpiration}`);\n\ninterface ExistsArgs {\n key: string;\n now: number;\n}\n\nconst existsValue = defineStatement(`SELECT\n 1 AS present\nFROM\n stash_keys\nWHERE\n KEY = :key\n AND ${visibleExpiration}`);\n\ninterface TypeArgs {\n key: string;\n now: number;\n}\n\nconst typeValue = defineStatement(`SELECT\n TYPE\nFROM\n stash_keys\nWHERE\n KEY = :key\n AND ${visibleExpiration}`);\n\ninterface UpdateExpirationArgs {\n expiresAt: number;\n key: string;\n now: number;\n}\n\nconst updateExpirationValue = defineStatement(\n `UPDATE stash_keys\nSET\n expires_at = :expiresAt,\n version = version + 1\nWHERE\n KEY = :key\n AND ${visibleExpiration} RETURNING 1 AS updated`,\n);\n\ninterface PersistArgs {\n key: string;\n now: number;\n}\n\nconst persistValue = defineStatement(`UPDATE stash_keys\nSET\n expires_at = NULL,\n version = version + 1\nWHERE\n KEY = :key\n AND expires_at IS NOT NULL\n AND ${visibleExpiration} RETURNING 1 AS updated`);\n\ninterface TtlArgs {\n key: string;\n now: number;\n}\n\nconst ttlValue = defineStatement(`SELECT\n expires_at\nFROM\n stash_keys\nWHERE\n KEY = :key\n AND ${visibleExpiration}`);\n\ninterface CleanupArgs {\n now: number;\n}\n\nconst cleanupExpired = defineStatement(`DELETE FROM stash_keys\nWHERE\n expires_at IS NOT NULL\n AND expires_at <= :now RETURNING 1 AS deleted`);\n\nfunction deleteValues(keys: string[], now: number): SqlStatement {\n const keyNames = keys.map((_, index) => `key${index}`);\n const args: Record = { now };\n for (const [index, key] of keys.entries()) {\n args[`key${index}`] = key;\n }\n return {\n sql: `DELETE FROM stash_keys\nWHERE\n KEY IN (${keyNames.map((name) => `:${name}`).join(\", \")})\n AND ${visibleExpiration} RETURNING 1 AS deleted`,\n args,\n };\n}\n\nconst textEncoder = new TextEncoder();\nconst textDecoder = new TextDecoder();\n\nfunction asBytes(value: unknown): Uint8Array {\n if (value instanceof Uint8Array) return new Uint8Array(value);\n if (value instanceof ArrayBuffer) return new Uint8Array(value.slice(0));\n if (ArrayBuffer.isView(value)) {\n return new Uint8Array(\n value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength),\n );\n }\n throw new TypeError(\"Townstash received a non-binary value from SQLite\");\n}\n\nfunction assertSafeMilliseconds(value: number, label: string): void {\n if (!Number.isSafeInteger(value) || value < 0) {\n throw new RangeError(`${label} must be a non-negative safe integer`);\n }\n}\n\nfunction expirationFromTtl(ttlMs: number, now: number): number {\n assertSafeMilliseconds(ttlMs, \"ttlMs\");\n const expiresAt = now + ttlMs;\n if (!Number.isSafeInteger(expiresAt)) {\n throw new RangeError(\n \"ttlMs produces an expiration outside the supported range\",\n );\n }\n return expiresAt;\n}\n\nfunction expirationFromDate(expiresAt: Date): number {\n if (!(expiresAt instanceof Date) || Number.isNaN(expiresAt.getTime())) {\n throw new TypeError(\"expiresAt must be a valid Date\");\n }\n return expiresAt.getTime();\n}\n\nfunction expirationFromOptions(\n options: SetOptions,\n now: number,\n): number | null {\n if (options.ttlMs !== undefined) {\n return expirationFromTtl(options.ttlMs, now);\n }\n if (options.expiresAt !== undefined) {\n return expirationFromDate(options.expiresAt);\n }\n return null;\n}\n\nfunction validateExpirationOptions(options: SetOptions): void {\n if (options.ttlMs !== undefined && options.expiresAt !== undefined) {\n throw new TypeError(\n \"Townstash set options ttlMs and expiresAt are mutually exclusive\",\n );\n }\n if (\n options.keepTtl === true &&\n (options.ttlMs !== undefined || options.expiresAt !== undefined)\n ) {\n throw new TypeError(\n \"Townstash set option keepTtl cannot be combined with expiration\",\n );\n }\n if (options.ttlMs !== undefined) {\n assertSafeMilliseconds(options.ttlMs, \"ttlMs\");\n }\n if (options.expiresAt !== undefined) expirationFromDate(options.expiresAt);\n}\n\nfunction assertValidClock(now: number): void {\n if (!Number.isSafeInteger(now)) {\n throw new RangeError(\n \"Townstash clock must return a safe integer timestamp\",\n );\n }\n}\n\nfunction assertCounterAmount(by: number): number {\n if (!Number.isInteger(by)) {\n throw new TypeError(\"Townstash counter amount must be an integer\");\n }\n if (!Number.isSafeInteger(by)) {\n throw new RangeError(\"Townstash counter amount must be a safe integer\");\n }\n return by;\n}\n\nfunction serializeJson(value: unknown): string {\n const serialized = JSON.stringify(value);\n if (serialized === undefined) {\n throw new TypeError(\n \"Townstash JSON values must serialize to a JSON value, not undefined\",\n );\n }\n return serialized;\n}\n\nfunction parseJson(key: string, value: string): T {\n try {\n return JSON.parse(value) as T;\n } catch (error) {\n const detail = error instanceof Error ? `: ${error.message}` : \"\";\n throw new SyntaxError(\n `Townstash value for key ${\n JSON.stringify(\n key,\n )\n } is not valid JSON${detail}`,\n );\n }\n}\n\nfunction prefixedStash(client: Stash, prefix: string): Stash {\n const addPrefix = (key: string) => `${prefix}${key}`;\n\n return {\n get: (key) => client.get(addPrefix(key)),\n getBytes: (key) => client.getBytes(addPrefix(key)),\n getJSON: (key: string) => client.getJSON(addPrefix(key)),\n set: (key, value, options) => client.set(addPrefix(key), value, options),\n setBytes: (key, value, options) =>\n client.setBytes(addPrefix(key), value, options),\n setJSON: (key: string, value: T, options?: SetOptions) =>\n client.setJSON(addPrefix(key), value, options),\n del: (...keys) => client.del(...keys.map(addPrefix)),\n exists: (key) => client.exists(addPrefix(key)),\n type: (key) => client.type(addPrefix(key)),\n expire: (key, ttlMs) => client.expire(addPrefix(key), ttlMs),\n expireAt: (key, expiresAt) => client.expireAt(addPrefix(key), expiresAt),\n persist: (key) => client.persist(addPrefix(key)),\n ttl: (key) => client.ttl(addPrefix(key)),\n cleanup: () => client.cleanup(),\n incr: (key, by) => client.incr(addPrefix(key), by),\n decr: (key, by) => client.decr(addPrefix(key), by),\n withPrefix: (nextPrefix) => prefixedStash(client, `${prefix}${nextPrefix}`),\n };\n}\n\n/** Internal construction seam used by the real-SQLite integration suite. */\nexport function createStash(\n database: SqliteClient,\n options: StashOptions = {},\n): Stash {\n let initialization: Promise | undefined;\n const now = options.now ?? Date.now;\n\n function currentTime(): number {\n const value = now();\n assertValidClock(value);\n return value;\n }\n\n function initialize(): Promise {\n initialization ??= database.batch(schemaStatements).then(() => undefined);\n return initialization;\n }\n\n async function setBytes(\n key: string,\n value: Uint8Array,\n options: SetOptions = {},\n ): Promise {\n if (options.nx === true && options.xx === true) {\n throw new TypeError(\n \"Townstash set options nx and xx are mutually exclusive\",\n );\n }\n validateExpirationOptions(options);\n await initialize();\n const mode: UpsertArgs[\"mode\"] = options.nx === true\n ? 1\n : options.xx === true\n ? 2\n : 0;\n const current = currentTime();\n const expiresAt = expirationFromOptions(options, current);\n const keepTtl: UpsertArgs[\"keepTtl\"] = options.keepTtl === true ? 1 : 0;\n const result = await database.execute(\n upsertValue({\n key,\n value: new Uint8Array(value),\n expiresAt,\n mode,\n now: current,\n keepTtl,\n }),\n );\n return result.rows.length > 0;\n }\n\n async function getBytes(key: string): Promise {\n await initialize();\n const result = await database.execute(\n selectValue({ key, now: currentTime() }),\n );\n const row = result.rows[0];\n if (!row) return undefined;\n if (row.type !== \"string\") {\n throw new TypeError(\n `Townstash does not support value type ${String(row.type)}`,\n );\n }\n return asBytes(row.value);\n }\n\n async function getJSON(key: string): Promise {\n const value = await getBytes(key);\n return value === undefined\n ? undefined\n : parseJson(key, textDecoder.decode(value));\n }\n\n async function del(...keys: string[]): Promise {\n if (keys.length === 0) return 0;\n await initialize();\n const result = await database.execute(deleteValues(keys, currentTime()));\n return result.rows.length;\n }\n\n async function exists(key: string): Promise {\n await initialize();\n const result = await database.execute(\n existsValue({ key, now: currentTime() }),\n );\n return result.rows.length > 0;\n }\n\n async function type(key: string): Promise<\"string\" | \"none\"> {\n await initialize();\n const result = await database.execute(\n typeValue({ key, now: currentTime() }),\n );\n const row = result.rows[0];\n if (!row) return \"none\";\n if (row.type !== \"string\") {\n throw new TypeError(\n `Townstash does not support value type ${String(row.type)}`,\n );\n }\n return \"string\";\n }\n\n async function updateExpiration(\n key: string,\n expiresAt: number,\n current: number,\n ): Promise {\n await initialize();\n const result = await database.execute(\n updateExpirationValue({ expiresAt, key, now: current }),\n );\n return result.rows.length > 0;\n }\n\n async function expireAt(key: string, expiresAt: Date): Promise {\n const absoluteExpiration = expirationFromDate(expiresAt);\n await initialize();\n return await updateExpiration(key, absoluteExpiration, currentTime());\n }\n\n async function expire(key: string, ttlMs: number): Promise {\n assertSafeMilliseconds(ttlMs, \"ttlMs\");\n await initialize();\n const current = currentTime();\n return await updateExpiration(\n key,\n expirationFromTtl(ttlMs, current),\n current,\n );\n }\n\n async function persist(key: string): Promise {\n await initialize();\n const result = await database.execute(\n persistValue({ key, now: currentTime() }),\n );\n return result.rows.length > 0;\n }\n\n async function ttl(key: string): Promise {\n await initialize();\n const current = currentTime();\n const result = await database.execute(ttlValue({ key, now: current }));\n const row = result.rows[0] as { expires_at?: number | null } | undefined;\n if (!row) return undefined;\n return row.expires_at === null || row.expires_at === undefined\n ? -1\n : row.expires_at - current;\n }\n\n async function cleanup(): Promise {\n await initialize();\n const result = await database.execute(\n cleanupExpired({ now: currentTime() }),\n );\n return result.rows.length;\n }\n\n async function incrementBy(key: string, delta: number): Promise {\n await initialize();\n const current = currentTime();\n const result = await database.execute(\n incrementValue({ key, delta, now: current }),\n );\n const row = result.rows[0];\n if (row) {\n const value = Number(row.result);\n if (!Number.isFinite(value)) {\n throw new Error(\"Townstash counter returned an invalid result\");\n }\n return value;\n }\n\n const state = await database.execute(counterState({ key, now: current }));\n const currentState = state.rows[0];\n if (!currentState) {\n throw new Error(\"Townstash counter update did not complete\");\n }\n if (currentState.type !== \"string\") {\n throw new TypeError(\n `Townstash does not support value type ${String(currentState.type)}`,\n );\n }\n if (currentState.text_value !== currentState.canonical_value) {\n throw new TypeError(\n \"Townstash counter value must be a canonical signed 64-bit integer\",\n );\n }\n throw new RangeError(\n \"Townstash counter operation overflows a signed 64-bit integer\",\n );\n }\n\n async function incr(key: string, by = 1): Promise {\n return await incrementBy(key, assertCounterAmount(by));\n }\n\n async function decr(key: string, by = 1): Promise {\n return await incrementBy(key, -assertCounterAmount(by));\n }\n\n const client: Stash = {\n async get(key) {\n const value = await getBytes(key);\n return value === undefined ? undefined : textDecoder.decode(value);\n },\n getBytes,\n getJSON,\n async set(key, value, options) {\n return await setBytes(\n key,\n typeof value === \"string\" ? textEncoder.encode(value) : value,\n options,\n );\n },\n setBytes,\n async setJSON(key: string, value: T, options?: SetOptions) {\n return await setBytes(\n key,\n textEncoder.encode(serializeJson(value)),\n options,\n );\n },\n del,\n exists,\n type,\n expire,\n expireAt,\n persist,\n ttl,\n cleanup,\n incr,\n decr,\n withPrefix(prefix) {\n return prefixedStash(client, prefix);\n },\n };\n\n return client;\n}\n",[],[214,320],["D",1783870116679],[271,272],[214],"fd8e5f59-9186-4748-b4c4-599ca461a0de","3f6f89a6-7dba-11f1-9bcf-1607ee4eb77e",["D",1783923547831],[],[221,336,337,33],"issues","townstash-v1","a51719b4-428a-49f9-a72f-e216ff41d3ed","06-v1-contract-and-release-readiness.md","3fc6266c-7dba-11f1-a60b-1607ee4eb77e","3f7e229a-7dba-11f1-a39f-1607ee4eb77e",124,["D",1783878036031],"# Harden and document the v1 contract\n\nStatus: resolved\n\n## What to build\n\nPrepare Townstash for v1 adoption by verifying the complete public client as one\ncoherent library, documenting its supported semantics and deliberate Redis\ndeviations, and providing usage guidance that does not imply server, protocol,\ndistributed-lock, or performance guarantees the SQLite-backed library does not\nprovide.\n\nThe release contract and documentation must remain consistent with\n[ADR-0001](../../../adr/0001-use-val-scoped-sqlite.md),\n[ADR-0002](../../../adr/0002-flat-binary-safe-keyspace.md), and\n[ADR-0003](../../../adr/0003-command-correctness-at-execution-time.md).\n\n## Acceptance criteria\n\n- [x] The canonical public surface matches the approved v1 contract for string\n values, conditional writes, expiration, key inspection and deletion,\n counters, JSON helpers, and prefixes.\n- [x] An integration suite exercises representative workflows through the\n exported `stash` client against the real SQLite adapter. The local suite\n uses the real SQLite adapter through the public client construction seam;\n the published entry-point workflow is opt-in in a Val Town-connected\n environment because the entry point is bound to the hosted SQLite API.\n- [x] Initialization is verified to be repeatable without losing existing data.\n V1 has no versioned migration path, so no unsupported migration behavior\n is presented as complete.\n- [x] Documentation includes import and usage examples for text, bytes, JSON,\n expiration, conditional writes, counters, deletion, and prefixed clients.\n- [x] Documentation clearly describes binary-safe storage, the flat keyspace,\n lazy expiration, atomicity boundaries, integer range, and return\n conventions.\n- [x] Redis-inspired compatibility and deliberate exclusions are stated plainly,\n including the lack of RESP, server compatibility, blocking operations,\n first-class collections, and Redis performance guarantees.\n- [x] The published library-val entry point exports the ready-to-use `stash`\n client and no unsupported v1 surface is presented as complete.\n- [x] Formatting, type checking, and the complete automated test suite pass\n using the repository's documented validation commands.\n\n## Blocked by\n\n- 02 — Add atomic conditional set behavior\n- 03 — Make key lifecycle behavior complete\n- 04 — Add atomic signed integer counters\n- 05 — Add JSON conveniences and compositional key prefixes\n\n## Comments\n\nImplemented and verified the v1 contract, adoption documentation, exact\nentry-point surface, representative real-SQLite workflows, lazy-expiration\ntiming, and wrong-type read failures. The published entry-point workflow is\navailable as an opt-in live integration test because `main.ts` is bound to the\nhosted Val Town SQLite service. V1 explicitly has no versioned migration path;\nschema initialization is repeatable and preserves existing data.\n\n`deno task check` and `deno task test` pass (26 tests including one ignored\nopt-in live test).\n",[],[221,336,337,336,339],"5a960918-b0e9-4bec-a83d-6f4b48267167","05-json-and-key-prefixes.md","3fb685e0-7dba-11f1-a39f-1607ee4eb77e",131,["D",1783878036169],"# Add JSON conveniences and compositional key prefixes\n\nStatus: resolved\n\n## What to build\n\nLet consumers explicitly serialize JSON values over Townstash strings and derive\nclients that prepend conventional key prefixes. Prefixed clients operate\ntransparently on the same flat keyspace and can be composed without implying\nnamespaces, isolation, or authorization.\n\nFollow [ADR-0002](../../../adr/0002-flat-binary-safe-keyspace.md): JSON and\nprefixes are conveniences over string values and complete flat keys, not\nadditional storage dimensions or types.\n\n## Acceptance criteria\n\n- [x] JSON values round-trip through explicit `setJSON` and `getJSON` helpers\n using documented serialization behavior.\n- [x] Missing JSON values return `undefined`, while malformed stored JSON\n produces a clear error without mutation.\n- [x] JSON writes support the same conditional and expiration options as other\n string writes.\n- [x] A prefixed client's commands are observationally equivalent to using the\n unprefixed client with the prefix prepended to each key.\n- [x] Prefixing applies consistently to single-key and multi-key commands.\n- [x] Calling `withPrefix` on a prefixed client composes prefixes in call order\n over the same flat keyspace.\n- [x] Tests make clear that prefixes are ergonomic sugar rather than persisted\n namespaces or security boundaries.\n- [x] All tests pass\n- [x] `deno task check` passes\n\n## Blocked by\n\n- 01 — Ship binary-safe string storage\n\n## Comments\n\nImplemented explicit JSON serialization over the binary-safe UTF-8 string API,\nincluding conditional and expiration options, missing-value behavior, clear\nmalformed-value errors, and rejection of top-level values that serialize to\n`undefined`. Added compositional prefix wrappers for every keyed command,\nincluding multi-key deletion; prefixes remain direct flat-key sugar and compose\nin call order. Added real-SQLite integration coverage and updated the PRD with\nthe serialization and prefix contract. `deno task check` and the full suite pass\n(23 tests).\n",[],[221,336,337,336,348],"dd920728-2c45-4890-ad93-63eb64a0bfc8","04-atomic-integer-counters.md","3fc209f6-7dba-11f1-a5bc-1607ee4eb77e",126,["D",1783878036109],"# Add atomic signed integer counters\n\nStatus: resolved\n\n## What to build\n\nAllow Val authors to increment and decrement integer string values atomically\nfor counters and rate limits. Missing and expired counters behave as zero,\nsigned amounts are supported, valid TTLs survive counter updates, and invalid\nstate cannot be partially changed.\n\nFollow [ADR-0002](../../../adr/0002-flat-binary-safe-keyspace.md) for\ninteger-as-string semantics and\n[ADR-0003](../../../adr/0003-command-correctness-at-execution-time.md) for\natomic validation and mutation.\n\n## Acceptance criteria\n\n- [x] `incr` and `decr` default to an amount of one and return the resulting\n integer.\n- [x] Both commands accept signed integer amounts, including decrementing by a\n negative amount.\n- [x] A missing or expired counter behaves as zero before the operation and\n becomes a visible string value containing the result.\n- [x] A counter update preserves the expiration of an existing visible value.\n- [x] Non-canonical integer strings, non-integer amounts, wrong-type values, and\n signed 64-bit overflow produce consistent errors without mutation.\n- [x] Parsing, validation, overflow checking, and mutation occur atomically\n rather than as an application-level read followed by a write.\n- [x] Real-adapter concurrency tests demonstrate that overlapping increments\n lose no updates.\n- [x] All tests pass\n- [x] `deno task check` passes\n\n## Blocked by\n\n- 03 — Make key lifecycle behavior complete\n\n## Comments\n\nImplemented atomic signed counter updates through the public client. Missing and\nexpired rows start from zero, visible TTLs are preserved, canonical\nsigned-64-bit values are validated in SQLite, and overflow or invalid state\nleaves the stored value unchanged. Added real-adapter coverage for signed\namounts, expiration behavior, boundary values, invalid amounts, wrong types,\noverflow, and overlapping increments. `deno task check` and the full test suite\npass.\n",[],[221,336,337,336,356],"a92d1d96-b40a-40c6-a0c1-21f4e2c8352e","03-key-lifecycle-and-cleanup.md","403d58f4-7dba-11f1-9c4e-1607ee4eb77e",128,["D",1783878036207],"# Make key lifecycle behavior complete\n\nStatus: resolved\n\n## What to build\n\nGive Val authors a complete key lifecycle: assign relative or absolute\nexpiration, inspect remaining lifetime, preserve or remove expiration, determine\nexistence and type, and delete one or more keys with useful return values. Every\nobserving command must treat an expired key exactly like a missing key,\nregardless of whether storage cleanup has run. Maintainers can reclaim expired\nrows independently without changing API behavior.\n\nFollow [ADR-0003](../../../adr/0003-command-correctness-at-execution-time.md):\nexpiration is resolved during each command, while cleanup only reclaims storage.\n\n## Acceptance criteria\n\n- [x] `set` accepts either an explicit millisecond TTL or an absolute expiration\n instant and rejects incompatible expiration options without mutation.\n- [x] `expire` and `expireAt` update the expiration of a visible key and report\n false for a missing or expired key.\n- [x] `ttl` reports the remaining lifetime in milliseconds for a visible\n expiring key and distinguishes a persistent key from a missing or expired\n key using the documented v1 convention.\n- [x] `persist` removes expiration from a visible key and reports whether it\n changed the key.\n- [x] `keepTtl` preserves the current expiration only when replacing an existing\n visible value.\n- [x] `get`, conditional `set`, `exists`, `type`, expiration commands, and\n deletion consistently treat expired keys as absent using a controllable\n clock in tests.\n- [x] `type` returns `string` for a visible v1 value and `none` for a missing or\n expired key.\n- [x] Multi-key `del` returns the number of visible keys removed and does not\n count missing or expired keys.\n- [x] Cleanup removes eligible expired storage while observable command results\n remain the same before and after cleanup.\n- [x] Behavior is covered through the public client against the real SQLite\n adapter without wall-clock sleeps.\n- [x] All tests pass\n- [x] `deno task check` passes\n\n## Blocked by\n\n- 02 — Add atomic conditional set behavior\n\n## Comments\n\nImplemented the complete v1 key lifecycle on the public client: relative and\nabsolute expiration, lazy visibility checks, expiration inspection and removal,\ntype/existence inspection, multi-key deletion, and explicit expired-row cleanup.\nAdded a controllable clock seam and real-SQLite coverage for boundary behavior,\nfailed operations on expired keys, TTL preservation, duplicate deletion keys,\nand cleanup invariants. `ttl` reports milliseconds, `-1` for persistent keys,\nand `undefined` for missing or expired keys.\n",[],[221,336,337,336,364],"9974c2f1-4a8a-41a3-83be-fd10dcc86b30","02-atomic-conditional-set.md","3fd29e2e-7dba-11f1-adbf-1607ee4eb77e",91,["D",1783871708191],2,"# Add atomic conditional set behavior\n\nStatus: resolved\n\n## What to build\n\nAllow Val authors to use only-if-absent and only-if-present writes for locks,\nidempotency claims, first-writer-wins state, and guarded updates. Conditions\nmust be decided in the same atomic database operation as the mutation so\nconcurrent callers cannot both succeed when only one should.\n\nFollow [ADR-0003](../../../adr/0003-command-correctness-at-execution-time.md):\nthe existence check and write must form one atomic command.\n\n## Acceptance criteria\n\n- [x] An unconditional valid set reports that the write occurred.\n- [x] `nx` writes only when the key is absent and returns false without mutation\n when the condition is not met.\n- [x] `xx` writes only when the key is present and returns false without\n mutation when the condition is not met.\n- [x] Mutually incompatible set options are rejected before database execution\n and do not mutate data.\n- [x] Conditional behavior is identical for text and byte values and composes\n with supported expiration options.\n- [x] A real-adapter concurrency test demonstrates that exactly one of multiple\n competing `nx` writes succeeds.\n\n## Blocked by\n\n- 01 — Ship binary-safe string storage\n\n## Comments\n\nImplemented atomic `nx` and `xx` set modes for text and byte values using one\nSQLite upsert statement with execution-time expiration checks and `RETURNING` to\nreport whether the write occurred. Added validation before schema/database\nexecution and real-adapter coverage for failed conditions, expired-key `nx`,\nbyte values, and competing writes. `deno task fmt`, `deno task check`, and the\nfull test suite pass.\n",[],[221,336,337,336,372],"914553fe-a332-4fff-829a-1b533dbb0b22","01-binary-safe-string-storage.md","3fecd46a-7dba-11f1-a5bc-1607ee4eb77e",86,["D",1783870146286],"# Ship binary-safe string storage\n\nStatus: resolved\n\n## What to build\n\nMake the canonical `stash` client usable for Townstash's foundational string\nvalue type. A Val author can import the client, initialize it repeatedly without\nharm, store text or arbitrary bytes in val-scoped SQLite, retrieve the value\nthrough the matching explicit API, and observe `undefined` for a missing key.\nReplacing an existing value follows the v1 set contract, including clearing an\nexisting expiration unless preservation is requested.\n\nCommand correctness must be exercised through the public client against the real\nSQLite adapter. Pure validation and serialization details may additionally use\nunit tests.\n\nFollow [ADR-0001](../../../adr/0001-use-val-scoped-sqlite.md) for the storage\nboundary and [ADR-0002](../../../adr/0002-flat-binary-safe-keyspace.md) for\nvalue and keyspace semantics.\n\n## Acceptance criteria\n\n- [x] Consumers can import the ready-to-use `stash` client from the Townstash\n library val without constructing or configuring a client.\n- [x] Schema initialization is idempotent and preserves existing supported data\n when run repeatedly.\n- [x] Text values round-trip predictably through `set` and `get`.\n- [x] Arbitrary byte sequences round-trip without UTF-8 conversion or data loss\n through the byte APIs.\n- [x] Missing keys return `undefined` from text and byte reads.\n- [x] An ordinary replacement succeeds and clears any existing expiration unless\n the caller explicitly requests TTL preservation.\n- [x] Public command behavior is covered against the real SQLite adapter.\n\n## Blocked by\n\nNone — can start immediately.\n\n## Comments\n\nImplemented the canonical val-scoped `stash` export, idempotent schema setup,\nbinary-safe text and byte APIs, replacement TTL behavior, and real-SQLite\nintegration coverage. `deno task fmt`, `deno task check`, and `deno task test`\npass.\n",[],[221,336,337,336,381],"65e005f7-ece4-407f-ac2b-88fbce6c820a",52,["D",1783837430770],[263,264,265,266,267,268],[221,336,337,336],"1a11735d-eb00-42bf-b53d-2487e6a25524","3f61cf28-7dba-11f1-9bcf-1607ee4eb77e",51,["D",1783837430676],[262,269],[221,336,337],"a43b9f5a-b5ad-4dee-a3c6-b41151144e68","a2a58b86-7e3e-11f1-a3ca-1607ee4eb77e","a26c5dfc-7e3e-11f1-aeef-1607ee4eb77e",220,["D",1783923547521],"# Named-args bind contract\n\nStatus: resolved\n\nBlocked by: none\n\n## Problem Statement\n\nTownstash's core binds its hand-written SQL with positional `?` placeholders.\nThe two load-bearing statements are the worst offenders: the conditional-set\nupsert binds 13 unlabeled positional args (with `mode` and the current timestamp\ninterleaved repeatedly), and the atomic counter increment binds 6 args of which\nfour are the same timestamp value. The pure validation helpers feeding these\nbinds are well tested, but the binding itself — the one place a real defect\nwould live — is an unchecked integer index. A silently reordered arg corrupts\nconditional-write or expiration semantics, and no test asserts arg order; a swap\nbetween two same-valued slots is undetectable by the existing suite in\nprinciple. Maintainers (human or agent) must correlate a TypeScript array with\nSQL `?` slots by counting placeholders.\n\n## Solution\n\nBind every statement by name instead of position. SQLite named parameters\n(`:name`) are natively supported by both adapters behind the `SqliteClient` seam\n(the local `node:sqlite` test adapter and Val Town's `std/sqlite`, which is\n`@libsql/client`), including reuse of one named parameter at multiple places in\na statement — so the counter's four duplicated timestamp slots collapse into a\nsingle `:now`. Each statement becomes a small statement module: the SQL text\nplus a typed args interface, welded together by one generic factory so that a\nwrong, missing, or excess key is a compile error at the call site. The `Stash`\ninterface — the surface users and tests see — does not change at all.\n\n## User Stories\n\n1. As a townstash maintainer, I want each SQL statement's arguments bound by\n name, so that I can read a call site and know which value lands in which\n placeholder without counting `?` slots.\n2. As a townstash maintainer, I want the argument-ordering contract to live in\n exactly one place per statement, so that a change to a statement's parameters\n is a local edit rather than a cross-referencing exercise.\n3. As a townstash maintainer, I want a typo'd or missing argument key to be a\n compile error, so that binding mistakes are caught before any test runs.\n4. As a townstash maintainer, I want the conditional-set mode encoding\n (`0`/`1`/`2`) and keepTtl flag expressed as literal-union types on the args\n interface, so that the encoding is documented at the type level instead of\n only in SQL branches.\n5. As a townstash maintainer, I want the counter increment to bind its timestamp\n once under a single name, so that a swap between duplicated timestamp slots\n is structurally impossible.\n6. As a townstash maintainer, I want every statement in the core to use the same\n binding idiom, so that a reader never has to determine which of two binding\n dialects a given call site speaks.\n7. As a future adapter author, I want the `SqliteClient` interface to accept\n named args as a record alongside positional arrays, so that my adapter knows\n named-parameter support is part of the contract it must satisfy.\n8. As a future adapter author, I want the named-parameter requirement recorded\n in an ADR, so that I don't discover the invariant by breaking it.\n9. As a townstash user, I want the `Stash` interface and every command's\n observable behaviour to remain byte-for-byte identical, so that this refactor\n is invisible to me.\n10. As a test author, I want the existing behaviour suite to pass unchanged, so\n that the conversion is demonstrably a pure refactor.\n11. As a test author, I want a compile-time assertion that the real Val Town\n client type satisfies `SqliteClient`, so that drift between townstash's\n structural types and the platform's types fails type-checking instead of\n surfacing in production.\n12. As a deployer, I want the gated live integration suite run once against the\n real platform adapter after this change, so that the named-args path is\n verified end-to-end where the library actually ships.\n13. As an AI agent navigating the codebase, I want statements and their arg\n types adjacent in the core module, so that understanding one command never\n requires bouncing between files.\n14. As a future maintainer adding a new command, I want a generic statement\n factory I can reuse, so that new statements get named binding and\n compile-time arg checking for free.\n\n## Implementation Decisions\n\n- **Scope: all statements convert.** Every bind site in the core (eleven today)\n moves from positional arrays to named `:name` placeholders with record args —\n not just the two risky statements. Uniformity is nearly free once the seam\n accepts records, and a mixed positional/named codebase was judged worse than\n the marginal diff.\n- **The `SqliteClient` seam widens, nothing else changes.** The statement input\n type's `args` field widens from array-only to\n `SqlValue[] | Record`. This is an un-narrowing back to the\n platform's own shape: Val Town's sqlite client is `@libsql/client`, whose\n `InArgs` is `Array | Record`. The real adapter\n therefore needs zero adaptation.\n- **The core stays import-free.** Townstash keeps its own structural\n `SqliteClient`/statement/value types as a deliberate subset of libsql's.\n libsql types are imported (type-only) exclusively in the local test file,\n where a compile-time assignability assertion pins compatibility: the libsql\n `Client` must satisfy `SqliteClient`, and townstash's statement type must be\n assignable to libsql's `InStatement`. Drift fails `deno check`.\n- **One generic factory enforces the SQL↔args pairing.** A single\n `defineStatement` helper welds each SQL constant to its args interface (shape\n from the design session):\n\n ```ts\n function defineStatement>(sql: string) {\n return (args: A): SqlStatement => ({ sql, args });\n }\n // usage: await database.execute(upsertValue({ key, value, expiresAt, mode, keepTtl, now }));\n ```\n\n Each statement gets a named args interface (e.g. `UpsertArgs`,\n `IncrementArgs`) with literal-union fields where the value set is closed\n (`mode: 0 | 1 | 2`, `keepTtl: 0 | 1`).\n- **SQL logic is untouched.** Only placeholder syntax changes; every WHERE/ CASE\n branch stays character-equivalent. The integer `mode` encoding is kept, not\n unpacked into separate nx/xx booleans — binding mechanism and SQL logic must\n not change in the same diff. (Unpacking is a possible follow-up.)\n- **Placement: statement modules stay in the core module** next to where the SQL\n constants already live. A separate statements file would have exactly one\n consumer — a hypothetical seam.\n- **Naming defaults:** `:name` prefix (verified working verbatim in both\n adapters); the timestamp argument is named `now`; the counter statement's four\n duplicated timestamp binds collapse to one `:now`.\n- **The local test adapter passes record args through** to `node:sqlite`'s\n prepared-statement API directly (object argument), spreading only when args is\n an array. Deno's `node:sqlite` was verified to support named parameters with\n bare or prefixed keys and repeated use of one parameter.\n- **ADR-0005** records the decision (\"bind SQL statements by named parameters\")\n and its consequence: named-parameter support is a required invariant of every\n `SqliteClient` adapter, with type compatibility pinned by the libsql\n assignability test.\n\n## Testing Decisions\n\n- **The `Stash` interface is the test surface**; this refactor adds no new\n runtime seams and must not test past the interface. A good test here is the\n existing kind: drive commands through `createStash` against the real in-memory\n SQLite engine and assert observable behaviour (per ADR-0003 and ADR-0004),\n never inspecting SQL text or arg objects.\n- **The conversion is verified by the suite staying green unchanged.** The\n existing local suite — nx/xx/keepTtl conditionals, relative and absolute\n expiration, counter overflow/underflow/canonicalization, validation-before- DB\n call-count assertions, and both 32-way concurrency tests — passes with no\n behavioural test edits. Test-adapter plumbing for record args is the only\n expected test-file change besides the new assignability assertion.\n- **Compile-time checks are tests.** `deno check` must pass, and the new\n type-level assignability block (libsql `Client` vs `SqliteClient`) lives in\n the local test file. It has no runtime component.\n- **One live verification run.** After local green, deploy and run the Val Town\n plain-script suite with `TOWNSTASH_LIVE_INTEGRATION=1` to exercise the\n named-args path against the real `std/sqlite` adapter end-to-end. Prior art:\n the existing gated live smoke test in the Val Town suite.\n\n## Out of Scope\n\n- Unpacking the conditional-set `mode` integer into separate nx/xx boolean\n parameters (clean follow-up diff, same verification suite).\n- The adapter conformance suite across both `SqliteClient` adapters (candidate 3\n of the 2026-07-12 architecture review; this spec's live run is a one-shot\n check, not the durable suite).\n- Any change to the `Stash` interface, command semantics, error messages, or\n schema.\n- The other architecture-review candidates (counter-rule consolidation,\n prefix-wrapper absorption, codec seam).\n- Adopting libsql types inside the core, or adding any runtime import to it.\n\n## Further Notes\n\n- Origin: architecture review of 2026-07-12 (top recommendation), refined in a\n grilling session; all decisions above were confirmed by the maintainer.\n- The libsql out-value type documents that BLOBs come back as `ArrayBuffer` on\n the real platform — this is why the byte-coercion helper's `ArrayBuffer`\n branches exist and are only unreachable under the local test adapter. Relevant\n context for the future conformance-suite work, not for this change.\n- Val Town's `std/sqlite` is a thin re-export of `@libsql/client@0.17.2/web`;\n the pinned version matters only for the type-only import in the test file.\n\n## Outcome\n\nThe named-args binding contract is complete. All eleven core statements use\ntyped named arguments, the local SQLite suite and compile-time adapter checks\npass, and the deployed Val Town client passed the gated plain-script suite with\n`2 passed, 0 failed, 0 ignored (of 2)`. During live verification, the dynamic\n`del` query was corrected to interpolate the shared visible-expiration predicate\nbefore the final successful run.\n",[],[221,336,407,33],"named-args-bind-contract","95f43160-5704-44a9-9c18-b3696efe69da","04-live-verification-on-val-town.md","c3235a9e-7e45-11f1-b7a0-1607ee4eb77e","c307e05c-7e45-11f1-96eb-1607ee4eb77e",221,["D",1783923547565],"# 04: Live verification on Val Town\n\nStatus: resolved\n\nBlocked by: 02, 03\n\n## Parent\n\n`docs/issues/named-args-bind-contract/PRD.md`\n\n## What to build\n\nThe named-args path is verified end-to-end where the library actually ships.\nAfter local green on the fully converted core, deploy to Val Town and run the\nplain-script test suite with `TOWNSTASH_LIVE_INTEGRATION=1`, exercising every\nconverted statement against the real `std/sqlite` adapter (libsql). Prior art:\nthe existing gated live smoke test in the Val Town suite.\n\nThis is the PRD's one-shot live check — not the durable cross-adapter\nconformance suite, which is a separate architecture-review candidate and out of\nscope here.\n\n## Acceptance criteria\n\n- [x] Val Town deployment updated with the converted core\n- [x] Plain-script suite run with `TOWNSTASH_LIVE_INTEGRATION=1` against the\n real platform adapter; all tests pass\n- [x] Run outcome recorded in a comment on this ticket\n\n## Blocked by\n\n- `02-convert-conditional-set-upsert.md`\n- `03-convert-counter-and-remaining-statements.md`\n\n## Comments\n\nAttempted 2026-07-12. `vt status` reports the deployed val is already current at\n`main@0..208`, so no deployment update was needed. The exact suite was run with\n`TOWNSTASH_LIVE_INTEGRATION=1 deno run --allow-all main_test.ts`.\n\nThe unauthenticated run failed before the first database assertion because the\nlocal process has no Val Town-injected token. A retry with the personal `vt` CLI\ntoken reached the hosted endpoint but Val Town rejected it because the SQLite\nscoped endpoint requires a token scoped to a val. The client then surfaced\n`TypeError: resp.body?.cancel is not a function` from `@libsql/hrana-client`\nwhile handling that response. The suite therefore has not yet been executed\ninside the Val Town runtime, where the required val-scoped token is injected;\nthe live acceptance check remains open.\n\nFollow-up: the maintainer then ran deployed version 210 in Val Town. The live\npath passed entry-point discovery, conditional writes, bytes, JSON, and\ncounters, then failed during cleanup because `del` sent the literal\n`visibleExpiration` identifier instead of the interpolated expiration predicate.\nFixed `src/stash.ts` to interpolate the shared fragment and pushed the\ncorrection. Awaiting one more live run against the updated deployment.\n\nCompleted: the maintainer reran the exact plain-script suite against the updated\ndeployment and reported the full success output:\n`2 passed, 0 failed,\n0 ignored (of 2)`, including the cleanup/deletion step. The\nlive verification acceptance criteria are complete.\n",[],[221,336,407,336,409],"49c1ad5a-528f-4808-9b8e-331b57f52f73","03-convert-counter-and-remaining-statements.md","c32be894-7e45-11f1-b3a7-1607ee4eb77e",219,["D",1783923547479],"# 03: Convert the counter and all remaining statements to named args\n\nStatus: resolved\n\nBlocked by: none\n\n## Parent\n\n`docs/issues/named-args-bind-contract/PRD.md`\n\n## What to build\n\nEvery remaining bind site in the core moves to named args, so that after this\nticket (together with 02) zero positional binds remain and a reader never has to\ndetermine which binding dialect a call site speaks.\n\n- The counter increment — 6 positional args today, four of them the same\n timestamp — collapses its duplicated timestamp slots into a single `:now`,\n making a swap between same-valued slots structurally impossible. The counter's\n overflow-diagnosis follow-up query converts too.\n- The shared visible-expiration SQL fragment switches its placeholder to `:now`;\n all statements embedding it (delete, exists, type, the expiration updates,\n persist, ttl, cleanup, counter-state) convert in the same diff, since editing\n the fragment touches them all at once.\n- The delete statement's variable-length key list gets generated names (`:key0`,\n `:key1`, …) built alongside its args record; this is the one statement whose\n SQL is assembled per call rather than a static constant, so it may use the\n factory differently or bypass it — but still binds by name.\n- Each static statement becomes a statement module via the `defineStatement`\n factory with its own typed args interface, adjacent to its SQL constant in the\n core module.\n- SQL logic untouched; only placeholder syntax changes.\n\n## Acceptance criteria\n\n- [x] Counter increment binds its timestamp exactly once under `:now`\n- [x] No positional array binds remain anywhere in the core module\n- [x] Delete with multiple keys binds each key by a generated name and passes\n the existing multi-key tests\n- [x] Counter tests (overflow/underflow/canonicalization, 32-way concurrency)\n and all lifecycle tests (expire, expireAt, persist, ttl, cleanup, exists,\n type, del) pass with no behavioural test edits\n- [x] `deno check` passes; `Stash` interface and observable behaviour unchanged\n\n## Blocked by\n\n- None — ticket 01 is resolved.\n\n## Answer\n\nConverted every remaining core bind site to named parameters. The counter now\nbinds `key`, `delta`, and one shared `now` value through a typed statement; the\ncounter-state diagnostic query uses the same named-args factory. Lifecycle\nstatements use adjacent typed argument interfaces and the shared `:now`\nexpiration fragment. `del` generates `:key0`, `:key1`, and so on next to its\nrecord args, preserving duplicate-key behavior for the existing multi-key\ncommand.\n\nThe `Stash` interface and SQL behavior are unchanged, and no behavioral test\nfiles were edited.\n\nValidation passed:\n\n- `deno task test` — 24 local SQLite tests and the entry-point test passed; the\n gated Val Town integration was skipped\n- `deno check --allow-import main.ts main_test.ts src/stash.ts src/stash_test.ts`\n- `deno lint`\n- `deno fmt --check src/stash.ts src/stash_test.ts main.ts main_test.ts`\n",[],[221,336,407,336,418],"354b6e24-ac2d-4b0a-b069-66beb7e081c7","02-convert-conditional-set-upsert.md","c31c8f8e-7e45-11f1-89cc-1607ee4eb77e",223,["D",1783923547607],"# 02: Convert the conditional-set upsert to named args\n\nStatus: resolved\n\nBlocked by: 01\n\n## Parent\n\n`docs/issues/named-args-bind-contract/PRD.md`\n\n## What to build\n\nThe riskiest bind in the core — the conditional-set upsert behind `set` /\n`setBytes` / `setJSON`, currently 13 unlabeled positional args with `mode` and\nthe current timestamp interleaved repeatedly — binds by name. A maintainer\nreading the call site sees each value labeled once; a change to the statement's\nparameters becomes a local edit instead of a count-the-placeholders exercise.\n\n- The upsert becomes a statement module: `:name` placeholders plus an\n `UpsertArgs` interface, welded by the `defineStatement` factory from\n ticket 01.\n- Repeated slots collapse: `mode` (bound four times today), the current\n timestamp (`now`, bound five times), and the key each bind once under a single\n name.\n- The mode encoding and keepTtl flag are literal-union fields on the args\n interface (`mode: 0 | 1 | 2`, `keepTtl: 0 | 1`), documenting the encoding at\n the type level. The integer encoding itself is kept — unpacking into nx/xx\n booleans is explicitly out of scope (binding mechanism and SQL logic must not\n change in the same diff).\n- SQL logic untouched: every WHERE/CASE branch stays character-equivalent; only\n placeholder syntax changes.\n\n## Acceptance criteria\n\n- [x] Upsert binds entirely by `:name`; no positional args remain in this\n statement\n- [x] `UpsertArgs` uses literal unions for `mode` and `keepTtl`\n- [x] Each logical value (`mode`, `now`, key) appears exactly once in the args\n record\n- [x] Existing conditional-set tests (nx/xx/keepTtl, relative and absolute\n expiration, concurrency) pass with no behavioural test edits\n- [x] `deno check` passes; `Stash` interface and observable behaviour unchanged\n\n## Blocked by\n\n- `01-named-args-seam-factory-tracer.md`\n\n## Answer\n\nImplemented the conditional-set upsert as a typed named-args statement using the\n`defineStatement` factory. `UpsertArgs` documents the closed `mode` and\n`keepTtl` encodings, and the call site supplies each logical value once while\nthe SQL reuses named placeholders for the repeated branches. Existing SQL logic,\nthe `Stash` interface, and behavior tests remain unchanged.\n\nValidation passed:\n\n- `deno test --allow-all src/stash_test.ts` — 24 passed\n- `deno check --allow-import main.ts main_test.ts src/stash.ts src/stash_test.ts`\n- `deno lint`\n- `deno fmt --check src/stash.ts src/stash_test.ts main.ts main_test.ts`\n- `deno task test` — 24 local tests passed; the gated live test was skipped\n",[],[221,336,407,336,426],"a529e3e9-b0d6-4644-aceb-b3588a7e26e6","01-named-args-seam-factory-tracer.md","c33fcf30-7e45-11f1-96eb-1607ee4eb77e",222,["D",1783923547676],"# 01: Named-args seam, statement factory, and tracer conversion\n\nStatus: resolved\n\nBlocked by: none\n\n## Parent\n\n`docs/issues/named-args-bind-contract/PRD.md`\n\n## What to build\n\nMake named-parameter binding part of the `SqliteClient` contract and prove the\nwhole path with one converted statement. After this ticket, a maintainer can\nread the `get` command's bind site and see each value labeled by name, the local\nsuite passes unchanged, and any future adapter author finds the named-args\nrequirement recorded as an ADR and pinned by a compile-time check against the\nreal platform's types.\n\nConcretely, end to end:\n\n- The statement input type's `args` field accepts a record of named values\n alongside the existing positional array (an un-narrowing back to libsql's own\n `InArgs` shape, so the real Val Town adapter needs zero adaptation).\n- The local test adapter passes record args through to `node:sqlite`'s\n prepared-statement API as an object, spreading only when args is an array.\n- A type-only assignability block in the local test file pins compatibility both\n ways: the libsql `Client` must satisfy `SqliteClient`, and townstash's\n statement type must be assignable to libsql's `InStatement`. Drift fails\n `deno check`. The libsql import is type-only and lives exclusively in the test\n file — the core stays import-free.\n- A generic `defineStatement` factory welds each SQL constant to a typed args\n interface so a wrong, missing, or excess key is a compile error at the call\n site. Shape from the design session (decision-rich part only):\n\n ```ts\n function defineStatement >(sql: string) {\n return (args: A): SqlStatement => ({ sql, args });\n }\n ```\n\n- One simple statement — the select behind `get` — converts to `:name`\n placeholders via the factory as the tracer bullet. Statement modules live in\n the core module next to where the SQL constants already are.\n- ADR-0005 records the decision (\"bind SQL statements by named parameters\") and\n its consequence: named-parameter support is a required invariant of every\n `SqliteClient` adapter, with compatibility pinned by the libsql assignability\n test.\n\n## Acceptance criteria\n\n- [x] `SqliteClient` statement args accept\n `SqlValue[] | Record`\n- [x] Local test adapter executes record args against `node:sqlite` (object\n form), still spreading array args\n- [x] Compile-time assignability assertions (libsql `Client` vs `SqliteClient`;\n townstash statement vs libsql `InStatement`) live in the local test file\n and pass `deno check`\n- [x] `defineStatement` factory exists; a typo'd, missing, or extra arg key at a\n call site is a compile error\n- [x] The `get` select statement binds by `:name` through the factory\n- [x] ADR-0005 written\n- [x] Existing local behaviour suite passes with no behavioural test edits; SQL\n logic character-equivalent apart from placeholder syntax\n- [x] No runtime imports added to the core; `Stash` interface unchanged\n\n## Blocked by\n\n- None — can start immediately.\n\n## Answer\n\nImplemented and verified the named-args seam and `get` tracer. `SqlStatement`\nnow accepts named records alongside positional arrays, the local SQLite adapter\npasses records through as objects, and the local test file pins compatibility\nwith libsql's `Client` and `InStatement` types. The core defines typed\nstatements with `defineStatement` and the `get` query uses `:key` and `:now`.\nADR-0005 records the adapter invariant. No `Stash` API or behavior tests were\nchanged.\n\nValidation passed:\n\n- `deno test --allow-all src/stash_test.ts` — 24 passed\n- `deno check --allow-import main.ts main_test.ts src/stash.ts src/stash_test.ts`\n- `deno lint`\n- `deno fmt --check src/stash.ts src/stash_test.ts main.ts main_test.ts`\n",[],[221,336,407,336,434],"ac64c3ef-f587-4934-9f2a-4024d4e2e3fd",190,["D",1783897351503],[256,257,258,259],[221,336,407,336],"e2a86650-b7a3-403d-a606-9316ae98bdeb",184,["D",1783894290321],[255,260],[221,336,407],"33744be4-152c-4db7-92a1-b709f106077d","a2956ac6-7e3e-11f1-9a8e-1607ee4eb77e","a27d76f0-7e3e-11f1-b25d-1607ee4eb77e",224,["D",1783923547788],"# Absorb the prefix wrapper into the Stash module\n\nStatus: resolved\n\nBlocked by: none\n\n## Problem Statement\n\nTownstash's `withPrefix` is implemented as a shadow of the `Stash` interface: a\nwrapper module of eighteen one-line delegations whose only behaviour is\nprepending a string to keys. It is a shallow module by the deletion test —\ndeleting it would concentrate the key rule into one place rather than scatter\ncomplexity — and it is a standing locality trap: adding a new command to the\n`Stash` interface compiles cleanly without the corresponding wrapper edit,\nsilently dropping prefixing for that command on every prefixed client. Every\ninterface change pays a hidden parallel-edit tax.\n\n## Solution\n\nMove prefixing inside the `Stash` module itself. The command implementations are\nbuilt by an internal per-view factory parameterized by a prefix string; the root\nclient is the factory applied with the empty prefix, and `withPrefix` returns\nthe same implementation built with the concatenated prefix. The key rule\n(\"stored key = prefix + key\", plain text, composed in call order) lives in one\nplace, every current and future command gets prefixing for free, and the wrapper\nmodule is deleted. The `Stash` interface and all observable behaviour are\nunchanged.\n\n## User Stories\n\n1. As a townstash maintainer, I want prefixing implemented once inside the Stash\n module, so that the key rule has a single home instead of a shadow copy of\n the interface.\n2. As a townstash maintainer, I want new commands to be prefix-correct by\n construction, so that adding a method never requires remembering a parallel\n wrapper edit.\n3. As a townstash maintainer, I want the compiler to make \"prefix silently\n skipped\" impossible, so that the failure mode ceases to exist rather than\n being caught by review.\n4. As a townstash user, I want `withPrefix` to keep its exact semantics — plain\n text prepend, call-order composition, flat keyspace, no isolation — so that\n this refactor is invisible to me.\n5. As a townstash user, I want prefixed clients to keep sharing the parent's\n database connection, schema initialization, and clock, so that creating a\n prefixed view stays free of side effects.\n6. As a townstash user, I want `cleanup` through a prefixed client to remain\n global, so that storage reclamation behaviour does not change.\n7. As a test author, I want the entire existing suite to pass unchanged, so that\n the refactor is demonstrably behaviour-invariant.\n8. As an AI agent navigating the codebase, I want one implementation of the\n command set instead of an implementation plus a wrapper, so that\n understanding a command means reading one function.\n9. As a future maintainer, I want the deleted wrapper's behaviour pinned by the\n existing prefixed-client tests, so that any regression in composition or\n forwarding surfaces immediately.\n\n## Implementation Decisions\n\n- **The internal seam is a prefix string, not a transform function.** The\n per-view factory takes the prefix as a plain string; the root client uses the\n empty string; `withPrefix` concatenates. An `encodeKey`-style function\n parameter was considered and rejected: string concatenation is the only\n transform that exists, and a function-valued seam with one adapter is a\n hypothetical seam.\n- **Command implementations move into an inner per-view factory** inside the\n Stash factory. Each view gets its own closure set — the same allocation\n behaviour as the wrapper it replaces.\n- **The prefix is applied exactly once, at the innermost point** where a key is\n placed into a statement's arguments — never at public-method entry. The text\n getter/setter commands delegate to the byte commands internally, so\n entry-point encoding would double-prefix; the innermost placement makes that\n structurally impossible.\n- **Shared state stays in the outer factory closure:** the database client, the\n memoized schema-initialization promise, and the clock live above the per-view\n factory, so every view shares one initialization and one time source, exactly\n as today.\n- **Composition semantics are preserved verbatim:** prefixes compose in call\n order by string concatenation; the keyspace stays flat; the full prefixed key\n remains addressable from an unprefixed client; a prefix provides no isolation\n or authorization (per the flat-keyspace ADR). `cleanup` remains a global\n operation regardless of which view invokes it.\n- **The `Stash` interface, error modes, and messages are untouched.** The\n wrapper module is deleted outright; nothing else about the public surface\n moves.\n- **No new ADR.** No interface or platform contract changes; the resulting code\n shape is self-evident.\n- **Ordering constraint:** implement only after the named-args-bind-contract\n spec lands. Both changes restructure the same command bodies; the prefix\n application point is right next to the named-args bind sites.\n\n## Testing Decisions\n\n- **The `Stash` interface is the test surface**, and this change must not test\n past it. A good test drives commands through the public interface against the\n real in-memory SQLite engine and asserts observable behaviour (per the\n existing ADRs); no test inspects prefixes, closures, or SQL.\n- **No new tests.** The existing prefixed-client tests already pin the behaviour\n being preserved: call-order composition and root visibility of composed keys,\n cross-view `del` counting, full lifecycle/bytes/counter forwarding, and global\n `cleanup` through a prefixed view. They also catch the double-prefix failure\n mode directly (a doubled prefix breaks the root-visibility assertions\n immediately).\n- **The gate is the suite passing unchanged** plus type-checking: `deno test`\n and `deno check`, no behavioural test edits. No live Val Town run — the change\n never touches the storage seam, SQL text, or anything platform-facing.\n- Prior art: the two existing prefixed-client test blocks in the local\n `Deno.test` suite.\n\n## Out of Scope\n\n- Any change to `withPrefix` semantics (isolation, validation, reserved\n characters, persisted namespaces — all explicitly rejected by the\n flat-keyspace ADR).\n- The named-args bind conversion itself (separate spec, must land first).\n- The other 2026-07-12 architecture-review candidates: counter-rule\n consolidation, the SqliteClient conformance suite, the codec seam.\n- Any new key-transform capability (hashing, escaping, namespacing) — one\n adapter, no seam.\n\n## Further Notes\n\n- Origin: candidate 4 of the 2026-07-12 architecture review (\"Absorb the prefix\n wrapper into the Stash module\"), grilled to shared understanding with the\n maintainer on the same date.\n- Expected net effect on the core: roughly 25 lines of wrapper deleted, a\n factory nesting introduced, zero public-surface change. The deletion test\n motivated the candidate: removing the wrapper concentrates the key rule\n instead of relocating it.\n",[],[221,336,459,33],"absorb-prefix-wrapper","f6697ee7-8926-4e76-91d7-cda15235608e","c0eee85a-7e82-11f1-8c55-1607ee4eb77e",217,["D",1783923547283],[],[221,336,459,336],"b8671299-d4d3-4cb0-a6ba-9d1c950ff72a",185,["D",1783894290426],[252,253],[221,336,459],"abd74235-32cc-4cbd-95c6-ec534c904c40",50,["D",1783837430585],[251,254,261],[221,336],"cefe04c4-158a-4eca-952b-fc9f193cc3e9","2026-07-12-run-2-tightened.txt","9732206e-7e22-11f1-8bd4-1607ee4eb77e","972355ac-7e22-11f1-bffc-1607ee4eb77e",167,["D",1783882245576],"Tightened harness: median of 3×50 samples with per-run p50 [min–max] spread,\nisolated `del` (keys pre-seeded so only the delete is timed), and a\nconcurrency-width throughput sweep. This is the run BENCHMARKS.md reports.\n\nTownstash vs blob benchmark (namespace __townstash_bench__:cf779f6a-a4fb-4a5b-84e7-e9b899525c96:)\nconfig: iters=50 warmup=5 repeats=3\n========================================================================\n\n[set] small (64B)\n stash p50 46.0ms [40.5–47.0] p95 108.6ms p99 153.5ms mean 53.8ms (median of 3×50)\n blob p50 47.0ms [44.7–49.5] p95 95.1ms p99 117.4ms mean 52.5ms (median of 3×50)\n[get] small (64B)\n stash p50 19.7ms [12.6–34.0] p95 68.4ms p99 90.5ms mean 28.0ms (median of 3×50)\n blob p50 60.0ms [58.3–60.0] p95 103.9ms p99 123.6ms mean 59.9ms (median of 3×50)\n\n[set] medium (4096B)\n stash p50 39.9ms [30.9–50.1] p95 93.0ms p99 114.7ms mean 48.6ms (median of 3×50)\n blob p50 48.9ms [44.1–49.9] p95 95.3ms p99 118.9ms mean 53.6ms (median of 3×50)\n[get] medium (4096B)\n stash p50 13.2ms [8.7–27.1] p95 71.3ms p99 134.5ms mean 29.8ms (median of 3×50)\n blob p50 35.9ms [32.7–37.7] p95 67.3ms p99 81.7ms mean 40.6ms (median of 3×50)\n\n[set] large (262144B)\n stash p50 42.5ms [38.9–44.3] p95 108.6ms p99 147.2ms mean 51.0ms (median of 3×50)\n blob p50 48.1ms [42.1–48.6] p95 84.3ms p99 113.4ms mean 50.5ms (median of 3×50)\n[get] large (262144B)\n stash p50 13.3ms [13.0–19.1] p95 32.3ms p99 51.0ms mean 16.0ms (median of 3×50)\n blob p50 40.9ms [38.2–44.8] p95 72.1ms p99 118.7ms mean 43.1ms (median of 3×50)\n\n[del] (pre-seeded keys, delete only)\n stash p50 27.3ms [26.6–28.3] p95 63.5ms p99 66.5ms mean 33.0ms (median of 3×50)\n blob p50 26.1ms [26.0–30.5] p95 62.1ms p99 97.1ms mean 32.9ms (median of 3×50)\n\n[setJSON]\n stash p50 42.6ms [40.7–71.3] p95 108.9ms p99 187.6ms mean 57.1ms (median of 3×50)\n blob p50 49.9ms [43.3–107.7] p95 110.4ms p99 125.2ms mean 55.7ms (median of 3×50)\n[getJSON]\n stash p50 12.5ms [11.3–19.6] p95 58.8ms p99 72.2ms mean 23.2ms (median of 3×50)\n blob p50 44.7ms [40.9–49.4] p95 86.6ms p99 112.7ms mean 52.2ms (median of 3×50)\n\n[counter increment]\n stash.incr (atomic, 1 RT) p50 45.8ms [38.0–52.4] p95 82.1ms p99 106.6ms mean 48.6ms (median of 3×50)\n blob RMW (racy, 2 RT) p50 101.9ms [101.9–105.0] p95 168.5ms p99 238.1ms mean 108.3ms (median of 3×50)\n\n[concurrent set throughput] width sweep, 5 batches each\n width stash ops/s blob ops/s ratio(blob/stash)\n 1 31 20 0.64×\n 5 30 62 2.08×\n 10 45 108 2.41×\n 20 48 78 1.64×\n 50 52 139 2.70×\n\ncleanup: removed 521 stash keys, 521 blob keys\n",[],[221,485,477],"benchmarks","a479fc3e-73b2-4d23-bf0f-9a79fc3f810f","2026-07-12-run-1-initial-draft.txt","974e84ac-7e22-11f1-a188-1607ee4eb77e",170,["D",1783882245570],"Initial-draft harness: single pass (n=50), no repeats/brackets, `del` measured\nas set+del (not isolated). Superseded by run 2 for the headline numbers; kept\nfor provenance.\n\nTownstash vs blob benchmark (namespace __townstash_bench__:e9b57508-852e-4a17-8be7-5b22b6a11222:)\n========================================================================\n\n[set] small (64B)\n stash p50 33.1ms p95 72.2ms p99 77.6ms mean 41.1ms (n=50)\n blob p50 38.8ms p95 77.0ms p99 79.0ms mean 44.2ms (n=50)\n[get] small (64B)\n stash p50 12.7ms p95 62.6ms p99 100.8ms mean 23.5ms (n=50)\n blob p50 45.7ms p95 90.1ms p99 107.8ms mean 49.9ms (n=50)\n\n[set] medium (4096B)\n stash p50 37.5ms p95 76.0ms p99 158.6ms mean 42.7ms (n=50)\n blob p50 50.6ms p95 85.9ms p99 114.8ms mean 51.8ms (n=50)\n[get] medium (4096B)\n stash p50 22.1ms p95 68.7ms p99 91.3ms mean 27.8ms (n=50)\n blob p50 53.6ms p95 111.0ms p99 334.8ms mean 65.5ms (n=50)\n\n[set] large (262144B)\n stash p50 59.1ms p95 115.0ms p99 147.3ms mean 62.6ms (n=50)\n blob p50 47.0ms p95 72.5ms p99 113.6ms mean 49.6ms (n=50)\n[get] large (262144B)\n stash p50 41.8ms p95 77.7ms p99 215.3ms mean 45.6ms (n=50)\n blob p50 49.4ms p95 88.2ms p99 107.9ms mean 52.6ms (n=50)\n\n[del] (create then delete each iteration)\n stash p50 95.7ms p95 174.9ms p99 205.8ms mean 99.8ms (n=50)\n blob p50 92.8ms p95 165.7ms p99 280.6ms mean 92.7ms (n=50)\n\n[setJSON]\n stash p50 40.9ms p95 84.9ms p99 88.5ms mean 47.9ms (n=50)\n blob p50 43.4ms p95 97.0ms p99 129.7ms mean 53.7ms (n=50)\n[getJSON]\n stash p50 16.7ms p95 58.8ms p99 64.5ms mean 25.6ms (n=50)\n blob p50 56.1ms p95 82.7ms p99 96.0ms mean 51.3ms (n=50)\n\n[counter increment]\n stash.incr (atomic, 1 RT) p50 37.6ms p95 84.3ms p99 102.3ms mean 45.0ms (n=50)\n blob RMW (racy, 2 RT) p50 94.4ms p95 122.6ms p99 183.7ms mean 91.6ms (n=50)\n\n[concurrent set throughput] width=20 x 5 batches\n stash 52 ops/s (mean batch 381.6ms, 100 ops)\n blob 190 ops/s (mean batch 105.4ms, 100 ops)\n\ncleanup: removed 105 stash keys, 105 blob keys\n",[],[221,485,487],"e78d3deb-fb2e-4513-9623-91d0f827ebb7",166,["D",1783882245480],[248,249],[221,485],"1dbd9e66-c8b2-48b7-a71c-2e610aa52d8a","triage-labels.md","3fcbf0f6-7dba-11f1-8fde-1607ee4eb77e","3f50d204-7dba-11f1-8f0a-1607ee4eb77e",76,["D",1783870145621],"# Triage Labels\n\nThe skills speak in terms of five canonical triage roles. This file maps those\nroles to the actual label strings used in this repo's issue tracker.\n\n| Label in mattpocock/skills | Label in our tracker | Meaning |\n| -------------------------- | -------------------- | ---------------------------------------- |\n| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |\n| `needs-info` | `needs-info` | Waiting on reporter for more information |\n| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |\n| `ready-for-human` | `ready-for-human` | Requires human implementation |\n| `wontfix` | `wontfix` | Will not be actioned |\n\nWhen a skill mentions a role (e.g. \"apply the AFK-ready triage label\"), use the\ncorresponding label string from this table.\n\nEdit the right-hand column to match whatever vocabulary you actually use.\n",[],[221,508,500],"agents","de597148-157e-47e4-b33d-05eac66c146e","issue-tracker.md","3ff830d0-7dba-11f1-b5ea-1607ee4eb77e",78,["D",1783870145812],"# Issue tracker: Local Markdown\n\nIssues and PRDs for this repo live as markdown files in `docs/issues/`.\n\n## Conventions\n\n- One feature per directory: `docs/issues//`\n- The PRD is `docs/issues//PRD.md`\n- Implementation issues are `docs/issues//issues/-.md`,\n numbered from `01`\n- Triage state is recorded as a `Status:` line near the top of each issue file\n (see `triage-labels.md` for the role strings)\n- Comments and conversation history append to the bottom of the file under a\n `## Comments` heading\n\n## When a skill says \"publish to the issue tracker\"\n\nCreate a new file under `docs/issues//` (creating the directory if\nneeded).\n\n## When a skill says \"fetch the relevant ticket\"\n\nRead the file at the referenced path. The user will normally pass the path or\nthe issue number directly.\n\n## Wayfinding operations\n\nUsed by `/wayfinder`. The **map** is a file with one **child** file per ticket.\n\n- **Map**: `docs/issues//map.md` — the Notes / Decisions-so-far / Fog\n body.\n- **Child ticket**: `docs/issues//issues/NN-.md`, numbered from\n `01`, with the question in the body. A `Type:` line records the ticket type\n (`research`/`prototype`/`grilling`/`task`); a `Status:` line records\n `claimed`/`resolved`.\n- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked\n when every file it lists is `resolved`.\n- **Frontier**: scan `docs/issues//issues/` for files that are open,\n unblocked, and unclaimed; first by number wins.\n- **Claim**: set `Status: claimed` and save before any work.\n- **Resolve**: append the answer under an `## Answer` heading, set\n `Status: resolved`, then append a context pointer (gist + link) to the map's\n Decisions-so-far in `map.md`.\n",[],[221,508,510],"0f602559-c73e-4ff9-b0dc-a4e242dd7d71","domain.md","3fba94aa-7dba-11f1-9ce1-1607ee4eb77e",83,["D",1783870146096],"# Domain Docs\n\nHow the engineering skills should consume this repo's domain documentation when\nexploring the codebase.\n\n## Before exploring, read these\n\n- **`CONTEXT.md`** at the repo root, or\n- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one\n `CONTEXT.md` per context. Read each one relevant to the topic.\n- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In\n multi-context repos, also check `src//docs/adr/` for context-scoped\n decisions.\n\nIf any of these files don't exist, **proceed silently**. Don't flag their\nabsence; don't suggest creating them upfront. The `/domain-modeling` skill\n(reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates\nthem lazily when terms or decisions actually get resolved.\n\n## File structure\n\nSingle-context repo (most repos):\n\n```\n/\n├── CONTEXT.md\n├── docs/adr/\n│ ├── 0001-event-sourced-orders.md\n│ └── 0002-postgres-for-write-model.md\n└── src/\n```\n\nMulti-context repo (presence of `CONTEXT-MAP.md` at the root):\n\n```\n/\n├── CONTEXT-MAP.md\n├── docs/adr/ ← system-wide decisions\n└── src/\n ├── ordering/\n │ ├── CONTEXT.md\n │ └── docs/adr/ ← context-specific decisions\n └── billing/\n ├── CONTEXT.md\n └── docs/adr/\n```\n\n## Use the glossary's vocabulary\n\nWhen your output names a domain concept (in an issue title, a refactor proposal,\na hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift\nto synonyms the glossary explicitly avoids.\n\nIf the concept you need isn't in the glossary yet, that's a signal — either\nyou're inventing language the project doesn't use (reconsider) or there's a real\ngap (note it for `/domain-modeling`).\n\n## Flag ADR conflicts\n\nIf your output contradicts an existing ADR, surface it explicitly rather than\nsilently overriding:\n\n> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_\n",[],[221,508,518],"7476c2df-e6a3-4000-90f6-c09497669369",49,["D",1783837430475],[244,245,246],[221,508],"69ad60a4-4b86-4bab-a7e3-b6f8590fac7f","0005-bind-sql-statements-by-name.md","c316051a-7e45-11f1-96eb-1607ee4eb77e","3f3d4644-7dba-11f1-8f0a-1607ee4eb77e",191,["D",1783897351597],"# Bind SQL statements by named parameters\n\nTownstash binds SQL statement arguments by named parameters. Every statement\nthat accepts values uses named placeholders such as `:key` and passes a record\nof named values through the `SqliteClient` seam. The generic statement factory\nkeeps each statement's SQL and argument shape together so incorrect argument\nnames are compile-time errors at the call site.\n\n## Considered Options\n\n- **Named parameters:** makes each bind explicit at the call site, supports\n reusing one value in multiple SQL positions, and lets statement-specific\n argument types document closed encodings.\n- **Positional parameters:** is supported by SQLite, but requires maintainers to\n correlate an unlabeled array with every `?` in the SQL text.\n- **A separate adapter-specific binding layer:** could hide differences between\n clients, but would add a second statement representation and allow the core\n contract to drift from the platform adapter.\n\n## Consequences\n\nNamed-parameter support is a required invariant of every `SqliteClient` adapter.\nThe seam accepts both named records and positional arrays so existing schema\nstatements and future adapters remain compatible during incremental conversion,\nwhile all core bind sites move toward one uniform idiom.\n\nTownstash keeps structural SQLite types in the core and does not import libsql\nat runtime. The local test file pins assignability against the real libsql\n`Client` and `InStatement` types, so platform type drift fails `deno check`. The\nlocal `node:sqlite` adapter passes named records through as objects and\ncontinues to spread positional arrays.\n",[],[221,539,531],"adr","87b236b4-b581-4be6-8588-a4588e0ce4a2","0004-plain-script-tests-for-val-town.md","62ebb790-7e1b-11f1-8e3b-1607ee4eb77e",153,["D",1783879967586],"# Use `Deno.test` for local tests, plain scripts for Val Town tests\n\nTownstash tests split by where they must run:\n\n- **Local unit tests use `Deno.test`.** `src/stash_test.ts` drives the pure\n stash logic against an in-memory `node:sqlite` adapter and runs with\n `deno test`. Nothing about it needs the Val Town runtime, so the idiomatic\n Deno harness is the right tool.\n- **Val Town tests use a plain script runner.** `main_test.ts` exercises the\n real val (the `stash` entry point backed by `std/sqlite`), so it must be\n runnable on Val Town. The Val Town runtime executes a val as a top-level\n script and does not provide the Deno test harness — a file built around\n `Deno.test(...)` registers cases that never run there. So these tests are a\n `TestCase[]` iterated by a top-level `await runTests()` loop instead.\n\nThe deciding question for a new test is not \"which style do we prefer\" but \"does\nthis test need to run on Val Town?\"\n\n## Considered Options\n\n- **Split by runtime (chosen):** `Deno.test` where tests only run locally; a\n plain script runner where they must run on Val Town.\n- **Plain script runner everywhere:** uniform, but discards `deno test`'s\n filtering, reporting, and tooling for the local suite that has no reason to\n abandon it.\n- **`Deno.test` everywhere:** keeps one style, but the registered cases are\n inert in the Val Town runtime, so the suite that matters most cannot run where\n the library actually ships.\n\n## Consequences\n\nThe plain-script suite runs as a script: the runner throws (non-zero exit) when\nany case fails, so CI and the val runner still detect failures. Each case\ncarries its own `ignore` flag instead of `Deno.test`'s options bag — the live\nworkflow stays gated behind `TOWNSTASH_LIVE_INTEGRATION=1`. New Val Town tests\nare added as entries in the `tests` array; new local unit tests remain ordinary\n`Deno.test` calls. Tests that must run on Val Town may only use APIs it supports\n(e.g. `Deno.env.get`, `crypto.randomUUID`).\n",[],[221,539,541],"9f79febc-f49e-4fa8-bd12-1878a04ccb5c","0003-command-correctness-at-execution-time.md","3f991de8-7dba-11f1-b615-1607ee4eb77e",75,["D",1783870145598],"# Determine command results atomically at execution time\n\nEvery Townstash command determines visibility and performs any dependent\nmutation atomically in SQLite. Expired keys are logically absent during command\nexecution, so correctness never depends on an earlier application read or on\nbackground cleanup.\n\n## Considered Options\n\n- **Single SQL statements or transactional batches:** preserve conditional and\n concurrent command semantics.\n- **Application-level read then write:** is easier to implement but races across\n concurrent Val requests.\n- **Cleanup-driven expiration:** simplifies queries but can expose stale values\n whenever cleanup is delayed.\n\n## Consequences\n\nCleanup is only a storage-reclamation optimization. Commands that observe\nexistence must apply the same expiration rule, and mutations such as conditional\nset and increment cannot be implemented as separate reads and writes. Tests for\ncommand correctness use the real SQLite adapter, a controllable clock for\nexpiration, and concurrent operations where atomicity matters; mocks remain\nappropriate only for pure validation and serialization.\n",[],[221,539,549],"5232ee04-aacd-4995-a5ac-acff44a9fbda","0002-flat-binary-safe-keyspace.md","3fa61f02-7dba-11f1-a39f-1607ee4eb77e",82,["D",1783870145661],"# Use a flat keyspace of binary-safe string values\n\nTownstash models one flat Redis-style keyspace whose v1 values are binary-safe\nbyte sequences. Text, JSON, integer counters, and key prefixes are\ninterpretations or conveniences over that model rather than persisted namespaces\nor additional first-class value types.\n\n## Considered Options\n\n- **Flat keys with compositional prefixes:** keeps the full application-visible\n key as the identity and preserves familiar multi-key and future scanning\n semantics.\n- **A persisted namespace dimension:** partitions keys conveniently but\n introduces behavior Redis does not have and complicates cross-namespace\n commands.\n- **Automatically serialized JavaScript values:** is ergonomic initially but\n makes coercion surprising and obscures future first-class type boundaries.\n\n## Consequences\n\nThe default text API decodes the stored bytes, while explicit byte and JSON\nhelpers make serialization intent visible. Integers remain string values\ninterpreted by atomic numeric commands. Prefix wrappers only prepend text to\nkeys; they provide neither isolation nor authorization. Future hashes, sets,\nsorted sets, lists, and streams require dedicated storage and commands rather\nthan mutable JSON documents stored as strings.\n",[],[221,539,557],"7ab1100d-5085-4faa-8adb-22f2f4639505","0001-use-val-scoped-sqlite.md","3f9197ee-7dba-11f1-9acb-1607ee4eb77e",77,["D",1783870145600],"# Use val-scoped SQLite as the storage backend\n\nTownstash uses the SQLite database scoped to its library val as the sole v1\nstorage backend. SQLite was chosen over Blob because Redis-inspired conditional\nwrites, counters, expiration, and multi-step commands require atomic database\nmutations and transactions; the documented Blob interface does not provide those\nprimitives.\n\n## Considered Options\n\n- **Val-scoped SQLite:** supports conditional SQL, atomic updates, indexing, and\n transactional batches.\n- **Val-scoped Blob:** resembles a key/value store but would require race-prone\n read-modify-write operations for core commands.\n- **SQLite metadata with Blob values:** supports large binary payloads but\n introduces cross-store writes that cannot be committed atomically.\n\n## Consequences\n\nTownstash does not promise Redis's in-memory performance characteristics, and\nlarge values remain subject to SQLite's practical constraints. Blob or a hybrid\nbackend may be reconsidered only if a demonstrated large-value requirement\njustifies explicit orphan cleanup, versioning, and partial-failure semantics.\n",[],[221,539,565],"0d260c6b-0cd0-4b8c-a44f-3241e292ced1",48,["D",1783837430333],[238,239,240,241,242],[221,539],["D",1783837430189],[237,243,247,250],[221],["D",1783830414588],["D",1789526460011],{"_98":97,"_105":101},{"_98":97,"_99":-5,"_100":101,"_18":55,"_102":103,"_104":25},{"_13":87,"_32":88,"_43":42,"_89":44,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":45,"_96":97},"ctx",{"_80":-5,"_125":618,"_619":620,"_621":622,"_623":25,"_624":25,"_625":25,"_626":171,"_627":-5,"_628":-7,"_629":-7,"_630":196,"_631":25,"_632":25,"_633":-5,"_634":25,"_635":25,"_636":25,"_637":-5},"ENV",{"_589":590,"_591":592,"_593":88,"_594":595,"_596":597,"_598":599,"_600":601,"_602":603,"_604":605,"_606":607,"_608":609,"_610":611,"_612":613,"_614":615,"_616":617},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v225