[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_298":299,"_300":301},"routes/_app.x.$handle.$name",{"_96":95,"_31":43,"_104":86,"_26":105,"_13":14,"_106":-5,"_11":107,"_108":109,"_110":111,"_112":113,"_114":115,"_20":-5,"_116":-5,"_117":-5,"_118":24,"_119":120,"_121":24,"_122":-5,"_123":-5,"_124":125},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_41":42,"_31":43,"_36":44,"_45":-5,"_46":24,"_47":48,"_49":48,"_50":51,"_52":-5,"_18":53,"_54":-5,"_55":24,"_56":-5,"_57":-5,"_58":59,"_60":61,"_62":63,"_64":65,"_66":67,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":79,"_80":81,"_82":83,"_84":24},"version",58,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":-7,"_23":24,"_25":24,"_26":27,"_28":27},"file",{"_29":30,"_31":32,"_33":20,"_34":35,"_36":37,"_38":14,"_39":40,"_23":24},"previous","deleted",false,"deletedHere","path","docs/agents/domain.md","latestPath","fileId","3fba94aa-7dba-11f1-9ce1-1607ee4eb77e","name","domain.md","fileType","content","# Domain Docs\n\nHow the engineering skills should consume this repo's domain documentation when exploring 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 `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 multi-context repos, also check `src//docs/adr/` for context-scoped decisions.\n\nIf any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them 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, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.\n\nIf the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).\n\n## Flag ADR conflicts\n\nIf your output contradicts an existing ADR, surface it explicitly rather than silently overriding:\n\n> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_\n","createdAt",["D",1783837430934],"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",{"_96":95,"_103":99},"org",{"_96":95,"_97":-5,"_98":99,"_18":53,"_100":101,"_102":24},"branch",{"_13":85,"_31":86,"_41":40,"_87":42,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":43,"_94":95},"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",{"_41":42,"_31":43,"_36":293,"_45":-5,"_46":24,"_47":48,"_49":48,"_50":51,"_52":-5,"_18":53,"_54":-5,"_55":24,"_56":-5,"_57":-5,"_58":59,"_60":61,"_62":63,"_64":65,"_66":294,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":295,"_80":296,"_82":297,"_84":24},"tree",[183,195,196,197,198],"files",[183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198],"counts",{"_173":155,"_174":59,"_175":155,"_176":177,"_178":179},"contents",[126,127,128,129,130],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_41":166,"_31":167,"_29":168,"_134":-5,"_39":40,"_38":169,"_136":162,"_36":170,"_13":155,"_33":171,"_34":-5,"_23":24,"_141":-5,"_26":172},{"_41":158,"_31":159,"_29":160,"_134":-5,"_39":40,"_38":161,"_136":162,"_36":163,"_13":155,"_33":20,"_34":164,"_23":24,"_141":-5,"_26":165},{"_41":150,"_31":151,"_29":152,"_134":-5,"_39":40,"_38":153,"_136":24,"_36":154,"_13":155,"_33":20,"_34":156,"_23":24,"_141":-5,"_26":157},{"_41":143,"_31":144,"_29":145,"_134":-5,"_39":40,"_38":146,"_136":24,"_36":147,"_13":59,"_33":20,"_34":148,"_23":24,"_141":-5,"_26":149},{"_41":131,"_31":132,"_29":133,"_134":-5,"_39":40,"_38":135,"_136":24,"_36":137,"_13":138,"_33":139,"_34":140,"_23":24,"_141":-5,"_26":142},"7f7f3236-e4b6-41aa-965a-ac9427514808","main.ts","1a013e48-7db6-11f1-b08c-1607ee4eb77e","parentId",46,"latest",["D",1783835661307],2,"script","console.log(\"hello world\");","label",[132],"74a18908-369a-4703-896d-973e2154462b","deno.json","36597c4a-7dac-11f1-8c55-1607ee4eb77e",41,["D",1783835609442],"{\n\t\"compilerOptions\": {\n\t\t\"lib\": [\n\t\t\t\"dom\",\n\t\t\t\"dom.iterable\",\n\t\t\t\"dom.asynciterable\",\n\t\t\t\"deno.ns\",\n\t\t\t\"deno.unstable\"\n\t\t],\n\t\t\"noImplicitAny\": false,\n\t\t\"strict\": false,\n\t\t\"types\": [\"https://www.val.town/types/valtown.d.ts\"]\n\t},\n\t\"experimental\": {\n\t\t\"unstable-node-globals\": true,\n\t\t\"unstable-sloppy-imports\": true,\n\t\t\"unstable-temporal\": true,\n\t\t\"unstable-worker-options\": true\n\t},\n\t\"imports\": {\n\t\t\"@biomejs/biome\": \"npm:@biomejs/biome@^2.5.3\"\n\t},\n\t\"lint\": {\n\t\t\"files\": {\n\t\t\t\"include\": [\"deno:/https/esm.town/**/*\"]\n\t\t},\n\t\t\"rules\": {\n\t\t\t\"exclude\": [\"no-explicit-any\", \"no-import-prefix\"]\n\t\t}\n\t},\n\t\"lock\": false,\n\t\"nodeModulesDir\": \"auto\"\n}",[144],"077bfe4c-df53-4bdc-82be-b24b4d1bc572","biome.json","364cffce-7dac-11f1-9c3f-1607ee4eb77e",38,["D",1783831402375],0,"{\n\t\"$schema\": \"https://biomejs.dev/schemas/2.5.2/schema.json\",\n\t\"vcs\": {\n\t\t\"enabled\": false,\n\t\t\"clientKind\": \"git\",\n\t\t\"useIgnoreFile\": false\n\t},\n\t\"files\": {\n\t\t\"ignoreUnknown\": false\n\t},\n\t\"formatter\": {\n\t\t\"enabled\": true,\n\t\t\"indentStyle\": \"tab\"\n\t},\n\t\"linter\": {\n\t\t\"enabled\": true,\n\t\t\"rules\": {\n\t\t\t\"preset\": \"recommended\"\n\t\t}\n\t},\n\t\"javascript\": {\n\t\t\"formatter\": {\n\t\t\t\"quoteStyle\": \"double\"\n\t\t}\n\t},\n\t\"assist\": {\n\t\t\"enabled\": true,\n\t\t\"actions\": {\n\t\t\t\"source\": {\n\t\t\t\t\"organizeImports\": \"on\"\n\t\t\t}\n\t\t}\n\t}\n}\n",[151],"7529ead0-4fee-4931-9ae8-38a0877f8a58",".vtignore","365e30b4-7dac-11f1-904e-1607ee4eb77e",40,true,["D",1783831402416],".git\n.vscode\n.cursor\n.claude\n.DS_Store\nnode_modules\nvendor",[159],"a3f979cb-9774-4c49-a797-f5bd4c8469df","docs","3f266b0e-7dba-11f1-8f0a-1607ee4eb77e",47,["D",1783837430189],"directory",[167],"pulls","branches","forks","envVars",{"_180":59,"_182":155},"connections",{"_180":155,"_181":155},"count","unfilledCount","emptyCount",{"_41":166,"_31":167,"_29":168,"_134":-5,"_39":40,"_38":169,"_136":162,"_36":290,"_13":155,"_33":171,"_34":-5,"_23":24,"_141":-5,"_200":291,"_26":292},{"_41":285,"_31":268,"_29":262,"_134":168,"_39":40,"_38":286,"_136":162,"_36":287,"_13":155,"_33":171,"_34":-5,"_23":24,"_141":-5,"_200":288,"_26":289},{"_41":277,"_31":278,"_29":279,"_134":262,"_39":40,"_38":280,"_136":24,"_36":281,"_13":155,"_33":20,"_34":282,"_23":24,"_141":-5,"_200":283,"_26":284},{"_41":269,"_31":270,"_29":271,"_134":262,"_39":40,"_38":272,"_136":24,"_36":273,"_13":155,"_33":20,"_34":274,"_23":24,"_141":-5,"_200":275,"_26":276},{"_41":259,"_31":260,"_29":261,"_134":262,"_39":40,"_38":263,"_136":24,"_36":264,"_13":155,"_33":20,"_34":265,"_23":24,"_141":-5,"_200":266,"_26":267},{"_41":254,"_31":253,"_29":249,"_134":168,"_39":40,"_38":255,"_136":162,"_36":256,"_13":155,"_33":171,"_34":-5,"_23":24,"_141":-5,"_200":257,"_26":258},{"_41":248,"_31":32,"_29":30,"_134":249,"_39":40,"_38":14,"_136":24,"_36":250,"_13":155,"_33":20,"_34":35,"_23":24,"_141":-5,"_200":251,"_26":252},{"_41":243,"_31":221,"_29":238,"_134":168,"_39":40,"_38":244,"_136":162,"_36":245,"_13":155,"_33":171,"_34":-5,"_23":24,"_141":-5,"_200":246,"_26":247},{"_41":237,"_31":222,"_29":215,"_134":238,"_39":40,"_38":239,"_136":162,"_36":240,"_13":155,"_33":171,"_34":-5,"_23":24,"_141":-5,"_200":241,"_26":242},{"_41":232,"_31":221,"_29":226,"_134":215,"_39":40,"_38":233,"_136":162,"_36":234,"_13":155,"_33":171,"_34":-5,"_23":24,"_141":-5,"_200":235,"_26":236},{"_41":223,"_31":224,"_29":225,"_134":226,"_39":40,"_38":227,"_136":24,"_36":228,"_13":155,"_33":20,"_34":229,"_23":24,"_141":-5,"_200":230,"_26":231},{"_41":212,"_31":213,"_29":214,"_134":215,"_39":40,"_38":216,"_136":24,"_36":217,"_13":155,"_33":20,"_34":218,"_23":24,"_141":-5,"_200":219,"_26":220},{"_41":158,"_31":159,"_29":160,"_134":-5,"_39":40,"_38":161,"_136":162,"_36":209,"_13":155,"_33":20,"_34":164,"_23":24,"_141":-5,"_200":210,"_26":211},{"_41":150,"_31":151,"_29":152,"_134":-5,"_39":40,"_38":153,"_136":24,"_36":206,"_13":155,"_33":20,"_34":156,"_23":24,"_141":-5,"_200":207,"_26":208},{"_41":143,"_31":144,"_29":145,"_134":-5,"_39":40,"_38":146,"_136":24,"_36":203,"_13":59,"_33":20,"_34":148,"_23":24,"_141":-5,"_200":204,"_26":205},{"_41":131,"_31":132,"_29":133,"_134":-5,"_39":40,"_38":135,"_136":24,"_36":199,"_13":138,"_33":139,"_34":140,"_23":24,"_141":-5,"_200":201,"_26":202},["D",1783835661307],"children",[],[132],["D",1783835609442],[],[144],["D",1783831402375],[],[151],["D",1783831402416],[],[159],"b2c11863-01d8-43ce-9d67-531d63d03bd0","PRD.md","3faf0a40-7dba-11f1-a5bc-1607ee4eb77e","3f6f89a6-7dba-11f1-9bcf-1607ee4eb77e",56,["D",1783837431095],"# Spec: Townstash\n\n## Problem Statement\n\nVal Town provides val-scoped SQLite and Blob storage, but neither offers the ergonomic data-structure API, atomic counters, conditional writes, expiration behavior, and familiar key operations associated with Redis.\n\nDevelopers who need caching, idempotency, rate limiting, counters, queues, or small shared data structures must repeatedly design storage schemas and concurrency behavior themselves. A reusable Redis-inspired TypeScript library would provide consistent semantics for these use cases without requiring an external Redis service.\n\nThe library must be honest about its scope. It is a persistent library backed by Val Town storage, not an in-memory Redis server, a RESP-compatible endpoint, or a complete reimplementation of Redis performance and distributed-system behavior.\n\n## Solution\n\nProvide **Townstash**, a Val Town library val that exports a Redis-inspired TypeScript API backed by val-scoped SQLite. Consumers import the library from `townstash` and interact with its canonical exported client, `stash`. The first version will implement Redis-style string values, key expiration, conditional writes, deletion, existence checks, atomic integer counters, JSON convenience methods, and optional key-prefix helpers.\n\nValues at the core storage boundary are binary-safe sequences of bytes. Text and JSON APIs are conveniences layered over that representation. Numbers are not a separate value type: integer operations interpret the current string value as an integer, following the Redis model.\n\nThe library will preserve correctness under concurrent requests by expressing atomic operations as atomic database operations. Expired keys will be treated as absent during every command that observes key existence, regardless of whether background cleanup has run.\n\nFuture releases may add hashes, sets, sorted sets, lists, and streams as first-class value types. These types will not be simulated by silently storing mutable 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 can persist simple application state.\n2. As a Val author, I want to store and retrieve arbitrary bytes, so that string 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 that serialization behavior is predictable.\n4. As a Val author, I want missing and expired keys to produce the same 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 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 avoid accidentally creating state during an update.\n7. As a Val author, I want conditional writes to be atomic, so that concurrent 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 that cache and coordination records expire automatically.\n9. As a Val author, I want to add, replace, inspect, and remove a key's expiration, so that lifecycle management is available independently of value updates.\n10. As a Val author, I want expiration checks to be correct even if no cleanup 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 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 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 atomically, so that counters and rate limits remain correct under concurrency.\n14. As a Val author, I want increment and decrement methods to accept an optional signed integer amount, so that the API remains expressive and Redis-consistent.\n15. As a Val author, I want separate increment and decrement methods, so that 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 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 without changing them, so that invalid counter state is not silently corrupted.\n18. As a Val author, I want keys to occupy one flat keyspace, so that the storage model matches Redis key semantics.\n19. As a Val author, I want an optional prefixing wrapper, so that I can organize application keys without introducing first-class namespace behavior.\n20. As a Val author, I want prefixing to be transparent and compositional, so 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 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 consistently, so that data-model mistakes are visible.\n23. As a library maintainer, I want expired rows to be removable independently of command correctness, so that storage can be reclaimed without making cleanup timing part of the API contract.\n24. As a library maintainer, I want schema initialization to be idempotent, so that importing or initializing the library repeatedly is safe.\n25. As a library maintainer, I want atomic behavior tested against the real 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 not assume unsupported server, networking, blocking, or performance semantics.\n27. As a future library user, I want hashes, sets, sorted sets, lists, and streams to have first-class commands and storage behavior, so that collections do not require unsafe read-modify-write cycles over JSON strings.\n28. As a Val author, I want to import `stash` from the `townstash` library val, 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 backend because its documented interface does not provide the conditional-write, transactional, and atomic-update primitives required for Redis-like command semantics.\n- The product and library val are named **Townstash** and `townstash`, 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 standalone server package.\n- Account-global SQLite is not used by default. Each library instance operates within the SQLite database scoped to its val.\n- `stash` exposes a direct TypeScript API using familiar Redis-style command names where their semantics can be represented honestly. It does not implement the Redis Serialization Protocol or accept connections from existing Redis clients.\n- The keyspace is flat. A key contains its complete application-visible 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 passed through it. This is ergonomic sugar over the flat keyspace, not isolation or authorization.\n- The core first-version value type is the Redis string: a binary-safe byte sequence.\n- Text access is an explicit decoding convenience over byte values.\n- JSON access is an explicit serialization convenience over string values. JSON is not a first-class value type and does not provide path-level reads or mutations.\n- Integer counters are stored using string-compatible semantics rather than a separate public numeric type.\n- The public counter API provides both increment and decrement operations. Both accept an optional signed integer amount. Decrement is semantically equivalent to incrementing by the negated amount, so decrementing by a negative amount increments the value.\n- Numeric operations are atomic, treat a missing key as zero, and fail without mutation when the existing value is not a valid integer.\n- Conditional set behavior supports only-if-absent and only-if-present modes. Mutually incompatible options are rejected before execution.\n- Only-if-absent treats an expired key as absent. Only-if-present treats an expired key as absent.\n- Expiration is represented as an absolute instant. Public APIs may accept relative durations, but commands compare against a consistent current time when determining visibility.\n- Expiration is lazy for correctness: every relevant command excludes or replaces expired keys as appropriate.\n- Background or explicitly invoked cleanup is a storage-reclamation optimization only. Correctness never depends on its schedule.\n- Commands that combine existence checks and mutations must execute atomically. They must not use an application-level read followed by a separate write.\n- Multi-statement commands use the database's transactional batch capability when a single statement cannot express the required behavior.\n- Schema initialization and migrations are safe to run repeatedly.\n- The first version includes string get/set operations, byte and JSON conveniences, deletion, existence, expiration management, type inspection, conditional set, and integer increment/decrement.\n- Future first-class types are hashes, sets, sorted sets, lists, then streams. Each type receives dedicated data modeling and atomic commands rather than being encoded as a mutable JSON string.\n- Streams, if added, initially support persistent append and non-blocking reads. Blocking reads and consumer-group coordination require separate design work.\n- Redis compatibility is behavioral and selective. Command names and return conventions should remain familiar where doing so does not misrepresent the backend.\n\n## API and Data-Model Sketches\n\nThe following stubs capture decisions made during design. They are illustrative rather than final implementation prescriptions; names and return types may be refined 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 keyspace. In the example, `sessions.get(\"abc\")` reads the stored key `session:abc`.\n\n### First-version client surface\n\n```ts\ntype StashValue = string | Uint8Array;\n\ninterface SetOptions {\n /** Expire the key this many milliseconds after the operation succeeds. */\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\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 unconditional valid set returns `true`; an unsatisfied `nx` or `xx` condition returns `false`.\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 increments the stored value.\n\n### First-version key schema\n\nThe schema keeps one flat keyspace and reserves a type discriminator for future first-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 reserved for mutation tracking and potential future compare-and-swap behavior; it 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 expiration rule. In particular, `nx` may replace an expired row, while `xx`, `exists`, `type`, `expire`, `persist`, and `ttl` treat it as absent.\n\n### Atomic increment shape\n\nThe implementation should perform parsing, validation, arithmetic, overflow checking, and mutation as one database operation. It must not read the value into TypeScript and issue a separate write. The earlier design used the following 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 expired or wrong-type state correctly, reject non-canonical integers, preserve the existing TTL when required by the counter contract, and prevent signed 64-bit overflow without mutation.\n\n### Eventual first-class collection storage\n\nDedicated tables are the provisional direction for collection types; collections should 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 ownership, TTL behavior across collection rows, deletion, empty-collection behavior, and transactional coordination with `stash_keys` before implementation.\n\n## Seams & Testing Decisions\n\n- **Primary seam: public TypeScript client API backed by real val-scoped SQLite.** Tests invoke public commands and observe their results and errors without reaching through the client to assert SQL statements or table layouts. This seam was confirmed because correctness depends on real database atomicity and transaction behavior.\n- Tests verify externally observable command behavior: missing keys, byte preservation, text and JSON round trips, conditional-write results, expiration visibility, integer parsing, return values, and wrong-type errors.\n- Concurrency tests issue overlapping operations against the same database and key. They must demonstrate that only one competing only-if-absent write succeeds and that no increments are lost.\n- Expiration tests use a controllable clock exposed through the library's internal construction boundary. They do not rely on wall-clock sleeping.\n- Cleanup tests demonstrate that cleanup removes eligible storage while leaving API behavior unchanged before and after cleanup.\n- Prefix tests assert that a prefixed client is equivalent to applying the prefix to keys through the unprefixed client.\n- Schema tests verify that initialization can run more than once and that supported migrations preserve existing data.\n- Unit tests may cover pure serialization, validation, and key-prefix behavior, but mocks are not sufficient for command correctness.\n- Future data types will be tested through the same public client seam, 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 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 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 operations over string values.\n- Geospatial indexes, HyperLogLog, Bloom filters, other probabilistic structures, time series, arrays, and vector sets.\n- A hybrid SQLite-and-Blob value backend. Cross-store writes cannot be made atomic and are deferred until large binary values provide a demonstrated need.\n- Automatic key namespacing, tenant security boundaries, or access control based on prefixes.\n- Exact Redis latency, memory use, maximum value size, or algorithmic-complexity guarantees.\n\n## Settled API Decisions\n\n1. The default `get` method returns decoded text for ergonomics, paired with explicit `getBytes` and `setBytes` methods; the internal representation remains binary-safe.\n2. Relative expiration uses the explicit `ttlMs` option, while `expiresAt` accepts an absolute instant.\n3. A successful ordinary set clears an existing TTL unless the caller requests `keepTtl`.\n4. Counters guarantee signed 64-bit integers; overflow produces an error without mutation.\n\n## Open Questions\n\n1. Should the first release expose key scanning? If included, it should be a cursor-based, non-blocking API with clearly documented pattern semantics; a whole-keyspace `keys` operation should not be encouraged.\n2. Should future streams include consumer groups? Basic streams should be designed first; consumer groups require separate design because their 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 compatibility.\n- The likely eventual general-purpose type set is string, hash, set, sorted set, list, and stream. Cross-cutting semantics such as atomicity, expiration, type safety, and conditional mutation take priority over expanding that set.\n",[],[167,221,222,213],"issues","townstash-v1","ee1ef5cf-6077-45ec-ad4a-07584460d7e0","05-json-and-key-prefixes.md","3fb685e0-7dba-11f1-a39f-1607ee4eb77e","3f7e229a-7dba-11f1-a39f-1607ee4eb77e",57,["D",1783837431142],"# Add JSON conveniences and compositional key prefixes\n\nStatus: ready-for-agent\n\n## What to build\n\nLet consumers explicitly serialize JSON values over Townstash strings and derive clients that prepend conventional key prefixes. Prefixed clients operate transparently on the same flat keyspace and can be composed without implying namespaces, isolation, or authorization.\n\nFollow [ADR-0002](../../../adr/0002-flat-binary-safe-keyspace.md): JSON and prefixes are conveniences over string values and complete flat keys, not additional storage dimensions or types.\n\n## Acceptance criteria\n\n- [ ] JSON values round-trip through explicit `setJSON` and `getJSON` helpers using documented serialization behavior.\n- [ ] Missing JSON values return `undefined`, while malformed stored JSON produces a clear error without mutation.\n- [ ] JSON writes support the same conditional and expiration options as other string writes.\n- [ ] A prefixed client's commands are observationally equivalent to using the unprefixed client with the prefix prepended to each key.\n- [ ] Prefixing applies consistently to single-key and multi-key commands.\n- [ ] Calling `withPrefix` on a prefixed client composes prefixes in call order over the same flat keyspace.\n- [ ] Tests make clear that prefixes are ergonomic sugar rather than persisted namespaces or security boundaries.\n\n## Blocked by\n\n- 01 — Ship binary-safe string storage\n\n## Comments\n",[],[167,221,222,221,224],"65e005f7-ece4-407f-ac2b-88fbce6c820a",52,["D",1783837430770],[193],[167,221,222,221],"1a11735d-eb00-42bf-b53d-2487e6a25524","3f61cf28-7dba-11f1-9bcf-1607ee4eb77e",51,["D",1783837430676],[192,194],[167,221,222],"abd74235-32cc-4cbd-95c6-ec534c904c40",50,["D",1783837430585],[191],[167,221],"c304a0a2-9286-4850-ac53-176c474693b0","3f50d204-7dba-11f1-8f0a-1607ee4eb77e",["D",1783837430934],[],[167,253,32],"agents","7476c2df-e6a3-4000-90f6-c09497669369",49,["D",1783837430475],[189],[167,253],"739f90b5-cdb4-47e6-85ca-20c876d06228","0003-command-correctness-at-execution-time.md","3f991de8-7dba-11f1-b615-1607ee4eb77e","3f3d4644-7dba-11f1-8f0a-1607ee4eb77e",54,["D",1783837430911],"# Determine command results atomically at execution time\n\nEvery Townstash command determines visibility and performs any dependent mutation atomically in SQLite. Expired keys are logically absent during command execution, so correctness never depends on an earlier application read or on background cleanup.\n\n## Considered Options\n\n- **Single SQL statements or transactional batches:** preserve conditional and concurrent command semantics.\n- **Application-level read then write:** is easier to implement but races across concurrent Val requests.\n- **Cleanup-driven expiration:** simplifies queries but can expose stale values whenever cleanup is delayed.\n\n## Consequences\n\nCleanup is only a storage-reclamation optimization. Commands that observe existence must apply the same expiration rule, and mutations such as conditional set and increment cannot be implemented as separate reads and writes. Tests for command correctness use the real SQLite adapter, a controllable clock for expiration, and concurrent operations where atomicity matters; mocks remain appropriate only for pure validation and serialization.\n\n",[],[167,268,260],"adr","903704a6-1c3f-43f8-ac98-6cecf9a4278e","0002-flat-binary-safe-keyspace.md","3fa61f02-7dba-11f1-a39f-1607ee4eb77e",55,["D",1783837430945],"# Use a flat keyspace of binary-safe string values\n\nTownstash models one flat Redis-style keyspace whose v1 values are binary-safe byte sequences. Text, JSON, integer counters, and key prefixes are interpretations or conveniences over that model rather than persisted namespaces or additional first-class value types.\n\n## Considered Options\n\n- **Flat keys with compositional prefixes:** keeps the full application-visible key as the identity and preserves familiar multi-key and future scanning semantics.\n- **A persisted namespace dimension:** partitions keys conveniently but introduces behavior Redis does not have and complicates cross-namespace commands.\n- **Automatically serialized JavaScript values:** is ergonomic initially but 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 helpers make serialization intent visible. Integers remain string values interpreted by atomic numeric commands. Prefix wrappers only prepend text to keys; they provide neither isolation nor authorization. Future hashes, sets, sorted sets, lists, and streams require dedicated storage and commands rather than mutable JSON documents stored as strings.\n\n",[],[167,268,270],"c613b6a4-8f14-4f9f-bb59-cfe369fe2afb","0001-use-val-scoped-sqlite.md","3f9197ee-7dba-11f1-9acb-1607ee4eb77e",53,["D",1783837430899],"# Use val-scoped SQLite as the storage backend\n\nTownstash uses the SQLite database scoped to its library val as the sole v1 storage backend. SQLite was chosen over Blob because Redis-inspired conditional writes, counters, expiration, and multi-step commands require atomic database mutations and transactions; the documented Blob interface does not provide those primitives.\n\n## Considered Options\n\n- **Val-scoped SQLite:** supports conditional SQL, atomic updates, indexing, and transactional batches.\n- **Val-scoped Blob:** resembles a key/value store but would require race-prone read-modify-write operations for core commands.\n- **SQLite metadata with Blob values:** supports large binary payloads but introduces cross-store writes that cannot be committed atomically.\n\n## Consequences\n\nTownstash does not promise Redis's in-memory performance characteristics, and large values remain subject to SQLite's practical constraints. Blob or a hybrid backend may be reconsidered only if a demonstrated large-value requirement justifies explicit orphan cleanup, versioning, and partial-failure semantics.\n\n",[],[167,268,278],"0d260c6b-0cd0-4b8c-a44f-3241e292ced1",48,["D",1783837430333],[185,186,187],[167,268],["D",1783837430189],[184,188,190],[167],["D",1783830414588],["D",1789526460011],{"_96":95,"_103":99},{"_96":95,"_97":-5,"_98":99,"_18":53,"_100":101,"_102":24},{"_13":85,"_31":86,"_41":40,"_87":42,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":43,"_94":95},"ctx",{"_78":-5,"_123":331,"_332":333,"_334":335,"_336":24,"_337":24,"_338":24,"_339":162,"_340":-5,"_341":-7,"_342":-7,"_343":155,"_344":24,"_345":24,"_346":-5,"_347":24,"_348":24,"_349":24,"_350":-5},"ENV",{"_302":303,"_304":305,"_306":86,"_307":308,"_309":310,"_311":312,"_313":314,"_315":316,"_317":318,"_319":320,"_321":322,"_323":324,"_325":326,"_327":328,"_329":330},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","5015b8df46402d8bba4f485ecc37aec202b0e06b","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 · v58