acrylblends 0.7.8 → 0.8.1

package/plugins/acryl-door/src/page/protocol.ts

@@ -0,0 +1,213 @@
+/**
+ * The one shape of a door call, shared by the Host and the in-page driver (moved from `acryl-agent-control`, spec 041).
+ *
+ * The Host turns a verb's arguments into a {@link UiRequest}, sends it to the page over the channel, and gets a {@link UiResult} back.
+ * Everything crossing the channel is validated here once, so neither side trusts the other's JSON. The page imports this file too, so it
+ * lives with the page code and has no Node imports.
+ */
+
+/** The operations the driver performs on the page. */
+export const UI_OPS = ['snapshot', 'click', 'type', 'select', 'press', 'scroll', 'wait'] as const
+export type UiOp = (typeof UI_OPS)[number]
+
+/** Operations that change the page, so each call needs approval. `snapshot`, `scroll` and `wait` only look. */
+export const MUTATING_OPS: readonly UiOp[] = ['click', 'type', 'select', 'press']
+
+export const MAX_TEXT_LENGTH = 10_000
+export const MAX_WAIT_MS = 10_000
+export const MAX_SNAPSHOT_NODES = 1000
+export const DEFAULT_SNAPSHOT_NODES = 300
+
+/** Why a call did not do what was asked. Every failure is one of these, never a silent wrong action. */
+export type UiErrorCode =
+  | 'no-window'        // no page of the app is connected
+  | 'stale-ref'        // the element changed or was replaced since the snapshot
+  | 'unknown-ref'      // the ref was never issued
+  | 'sensitive'        // a password, token, API key or payment field
+  | 'protected'        // a control the agent may never operate (policy, approval, this plugin)
+  | 'not-actionable'   // hidden, disabled, or the wrong kind of element for the action
+  | 'not-found'        // a wait ended without the thing appearing
+  | 'killed'           // the user pressed the kill switch
+  | 'timeout'          // the page did not answer in time
+  | 'aborted'          // the call was cancelled
+  | 'unloaded'         // the driver went away mid-call
+  | 'disconnected'     // the page's channel dropped while the call was in flight
+  | 'invalid'          // malformed request
+
+export class UiControlError extends Error {
+  readonly code: UiErrorCode
+
+  constructor(code: UiErrorCode, message: string) {
+    super(message)
+    this.code = code
+    this.name = 'UiControlError'
+  }
+}
+
+/** One element in a snapshot. */
+export interface UiNode {
+  /** `<generation>.<n>`; valid only until the next snapshot. */
+  readonly ref: string
+  readonly role: string
+  readonly name: string
+  readonly depth: number
+  /** Short state words: `disabled`, `checked`, `expanded`, `selected`, `focused`, `protected`, ... */
+  readonly states: readonly string[]
+  /** The text of an editable field, when it is not sensitive. */
+  readonly value?: string
+  /** Heading level, when it is a heading. */
+  readonly level?: number
+}
+
+export interface UiSnapshot {
+  readonly generation: number
+  readonly title: string
+  readonly nodes: readonly UiNode[]
+  /** How many elements matched in all; more than `nodes.length` when the page was cut. */
+  readonly total: number
+  /** Pass to the next snapshot call to continue, or absent when this is everything. */
+  readonly nextCursor?: number
+}
+
+export type UiRequest =
+  | { readonly op: 'snapshot'; readonly cursor?: number; readonly maxNodes?: number }
+  | { readonly op: 'click'; readonly ref: string }
+  | { readonly op: 'type'; readonly ref: string; readonly text: string; readonly submit?: boolean; readonly clear?: boolean }
+  | { readonly op: 'select'; readonly ref: string; readonly option: string }
+  | { readonly op: 'press'; readonly key: string; readonly ref?: string }
+  | { readonly op: 'scroll'; readonly direction: 'up' | 'down' | 'left' | 'right'; readonly ref?: string; readonly amount?: number }
+  | { readonly op: 'wait'; readonly text?: string; readonly role?: string; readonly name?: string; readonly gone?: boolean; readonly timeoutMs?: number }
+
+/** What the page did, and to which control (for the audit log and the approval prompt). */
+export interface UiActionResult {
+  readonly ok: true
+  readonly target?: { readonly role: string; readonly name: string }
+  readonly detail?: string
+}
+
+export type UiResult = UiSnapshot | UiActionResult
+
+/**
+ * Messages the page and the Host exchange over the channel. The Host sends calls down the page's event stream (`event: call`); the page
+ * opens that stream with its window id and focus, and sends everything else up by POST, naming its window id.
+ */
+export type ChannelToPage =
+  | { readonly t: 'call'; readonly id: number; readonly request: UiRequest }
+export type ChannelToHost =
+  | { readonly t: 'focus'; readonly focused: boolean }
+  | { readonly t: 'result'; readonly id: number; readonly value: UiResult }
+  | { readonly t: 'error'; readonly id: number; readonly code: UiErrorCode; readonly message: string }
+
+const KEYS = /^(?:[A-Za-z0-9]|Enter|Escape|Tab|Backspace|Delete|Space|Arrow(?:Up|Down|Left|Right)|Home|End|PageUp|PageDown)$/
+const REF = /^\d{1,9}\.\d{1,6}$/
+
+const isRecord = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === 'object' && !Array.isArray(value)
+const invalid = (message: string): never => { throw new UiControlError('invalid', message) }
+
+function ref(value: unknown): string {
+  if (typeof value !== 'string' || !REF.test(value)) return invalid('ref must look like 3.17, from the latest snapshot')
+  return value
+}
+
+function text(value: unknown, max = MAX_TEXT_LENGTH): string {
+  if (typeof value !== 'string' || value.length > max || value.includes('\0')) return invalid(`text must be a string of at most ${String(max)} characters`)
+  return value
+}
+
+/** @param value - untrusted JSON. @throws UiControlError `invalid`. */
+export function parseUiRequest(value: unknown): UiRequest {
+  if (!isRecord(value) || typeof value.op !== 'string') return invalid('a call needs an op')
+  const op = value.op as UiOp
+  const only = (allowed: readonly string[]): void => {
+    const extra = Object.keys(value).find(key => key !== 'op' && !allowed.includes(key))
+    if (extra !== undefined) invalid(`unknown field ${extra}`)
+  }
+  switch (op) {
+    case 'snapshot': {
+      only(['cursor', 'maxNodes'])
+      const cursor = value.cursor === undefined ? undefined : Number(value.cursor)
+      const maxNodes = value.maxNodes === undefined ? undefined : Number(value.maxNodes)
+      if ((cursor !== undefined && (!Number.isInteger(cursor) || cursor < 0)) || (maxNodes !== undefined && (!Number.isInteger(maxNodes) || maxNodes < 1 || maxNodes > MAX_SNAPSHOT_NODES))) return invalid('cursor and maxNodes must be small positive integers')
+      return { op, ...(cursor === undefined ? {} : { cursor }), ...(maxNodes === undefined ? {} : { maxNodes }) }
+    }
+    case 'click': only(['ref']); return { op, ref: ref(value.ref) }
+    case 'type': {
+      only(['ref', 'text', 'submit', 'clear'])
+      if ((value.submit !== undefined && typeof value.submit !== 'boolean') || (value.clear !== undefined && typeof value.clear !== 'boolean')) return invalid('submit and clear must be true or false')
+      return { op, ref: ref(value.ref), text: text(value.text), ...(value.submit === undefined ? {} : { submit: value.submit }), ...(value.clear === undefined ? {} : { clear: value.clear }) }
+    }
+    case 'select': only(['ref', 'option']); return { op, ref: ref(value.ref), option: text(value.option, 500) }
+    case 'press': {
+      only(['key', 'ref'])
+      if (typeof value.key !== 'string' || !KEYS.test(value.key)) return invalid('key must be a single character or a name such as Enter, Escape, Tab or ArrowDown')
+      return { op, key: value.key, ...(value.ref === undefined ? {} : { ref: ref(value.ref) }) }
+    }
+    case 'scroll': {
+      only(['direction', 'ref', 'amount'])
+      if (value.direction !== 'up' && value.direction !== 'down' && value.direction !== 'left' && value.direction !== 'right') return invalid('direction must be up, down, left or right')
+      const amount = value.amount === undefined ? undefined : Number(value.amount)
+      if (amount !== undefined && (!Number.isFinite(amount) || amount <= 0 || amount > 10_000)) return invalid('amount must be between 1 and 10000 pixels')
+      return { op, direction: value.direction, ...(value.ref === undefined ? {} : { ref: ref(value.ref) }), ...(amount === undefined ? {} : { amount }) }
+    }
+    case 'wait': {
+      only(['text', 'role', 'name', 'gone', 'timeoutMs'])
+      const timeoutMs = value.timeoutMs === undefined ? undefined : Number(value.timeoutMs)
+      if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > MAX_WAIT_MS)) return invalid(`timeoutMs must be between 0 and ${String(MAX_WAIT_MS)}`)
+      if (value.gone !== undefined && typeof value.gone !== 'boolean') return invalid('gone must be true or false')
+      if (value.text === undefined && value.role === undefined && value.name === undefined) return invalid('wait needs text, or a role and name')
+      return {
+        op,
+        ...(value.text === undefined ? {} : { text: text(value.text, 500) }),
+        ...(value.role === undefined ? {} : { role: text(value.role, 60) }),
+        ...(value.name === undefined ? {} : { name: text(value.name, 500) }),
+        ...(value.gone === undefined ? {} : { gone: value.gone }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+      }
+    }
+    default: return invalid(`unknown op ${String(op)}`)
+  }
+}
+
+/** @param text - one `call` event's data from the Host. @throws when it is not a well-formed call. */
+export function parseChannelToPage(text: string): ChannelToPage {
+  const value: unknown = JSON.parse(text)
+  if (isRecord(value) && value.t === 'call' && typeof value.id === 'number' && Number.isSafeInteger(value.id)) {
+    return { t: 'call', id: value.id, request: parseUiRequest(value.request) }
+  }
+  throw new UiControlError('invalid', 'not a channel call')
+}
+
+/** Every code a {@link UiControlError} can carry, so a code read off the wire is validated, not cast. */
+export const UI_ERROR_CODES: readonly UiErrorCode[] = ['no-window', 'stale-ref', 'unknown-ref', 'sensitive', 'protected', 'not-actionable', 'not-found', 'killed', 'timeout', 'aborted', 'unloaded', 'disconnected', 'invalid']
+
+/** A window id the page chose: short, printable, so it can travel in a query string and a log line. */
+export const WINDOW_ID = /^[A-Za-z0-9-]{1,80}$/u
+
+/** @param value - one parsed message from the page; null when it is not a well-formed message. */
+export function parseChannelToHost(value: unknown): ChannelToHost | null {
+  if (!isRecord(value)) return null
+  if (value.t === 'focus' && typeof value.focused === 'boolean') return { t: 'focus', focused: value.focused }
+  if (value.t === 'result' && typeof value.id === 'number' && isRecord(value.value)) return { t: 'result', id: value.id, value: value.value as unknown as UiResult }
+  if (value.t === 'error' && typeof value.id === 'number' && typeof value.message === 'string' && UI_ERROR_CODES.includes(value.code as UiErrorCode)) {
+    return { t: 'error', id: value.id, code: value.code as UiErrorCode, message: value.message.slice(0, 500) }
+  }
+  return null
+}
+
+/** One line of the audit log: what the agent did, never what it typed. */
+export interface AuditEntry {
+  /** ISO time of the call. */
+  readonly at: string
+  readonly tool: string
+  /** The control touched, when the call had one. */
+  readonly target?: { readonly role: string; readonly name: string }
+  readonly outcome: 'ok' | 'refused' | 'failed'
+  /** The error code for a refusal or failure, or a short note for a success. */
+  readonly detail?: string
+  /**
+   * Whether the user was asked first (`asked`), approval was switched off (`none`), the call needed no
+   * approval (`not-needed`), or it came from an operator holding this run's secret (`token`, spec 041 TB30): authorized by the secret,
+   * which only the OS user who started the app can read, and watched by the person at the page through the indicator and its kill switch.
+   */
+  readonly approval: 'asked' | 'none' | 'not-needed' | 'token'
+}

package/plugins/acryl-door/src/page/snapshot-text.ts

@@ -0,0 +1,18 @@
+/** How a snapshot reads to an agent. Pure text, shared by the Host and the tests (no DOM). */
+
+import type { UiSnapshot } from './protocol.ts'
+
+/**
+ * The snapshot as compact text for an agent: one line per element, indented by depth.
+ * @param more - how to ask for the rest when the page was cut, given the cursor to continue from.
+ */
+export function renderSnapshot(snapshot: UiSnapshot, more: (cursor: number) => string = cursor => `call ui_snapshot with cursor ${String(cursor)}`): string {
+  const lines = snapshot.nodes.map((node) => {
+    const level = node.level === undefined ? '' : ` level=${String(node.level)}`
+    const states = node.states.length === 0 ? '' : ` [${node.states.join(', ')}]`
+    const value = node.value === undefined ? '' : ` value=${JSON.stringify(node.value)}`
+    return `${'  '.repeat(Math.min(node.depth, 8))}- ${node.role}${node.name === '' ? '' : ` ${JSON.stringify(node.name)}`}${level}${states}${value} [ref=${node.ref}]`
+  })
+  const rest = snapshot.nextCursor === undefined ? '' : `\n(${String(snapshot.total - snapshot.nextCursor)} more elements; ${more(snapshot.nextCursor)})`
+  return `Page: ${snapshot.title || '(untitled)'}\nSnapshot ${String(snapshot.generation)}, ${String(snapshot.nodes.length)} of ${String(snapshot.total)} elements:\n${lines.join('\n')}${rest}`
+}

package/plugins/acryl-door/src/page/user-input.ts

@@ -0,0 +1,24 @@
+/** Tracks when the user last used the page, so the agent yields to them. */
+
+/** Events only a real person produces: a script's `dispatchEvent` is never `isTrusted`. */
+const USER_EVENTS = ['pointerdown', 'mousedown', 'keydown', 'wheel', 'touchstart'] as const
+
+export class UserInputClock {
+  private last = Number.NEGATIVE_INFINITY
+
+  private readonly now: () => number
+
+  constructor(now: () => number = () => Date.now()) {
+    this.now = now
+  }
+
+  /** Milliseconds since the user last touched the page; Infinity when they have not. */
+  msSince = (): number => (this.last === Number.NEGATIVE_INFINITY ? Number.POSITIVE_INFINITY : this.now() - this.last)
+
+  /** Start listening. @returns disposer. */
+  attach(target: Document): () => void {
+    const handler = (event: Event): void => { if (event.isTrusted) this.last = this.now() }
+    for (const type of USER_EVENTS) target.addEventListener(type, handler, { capture: true, passive: true })
+    return () => { for (const type of USER_EVENTS) target.removeEventListener(type, handler, { capture: true }) }
+  }
+}

package/plugins/acryl-door/upstream.json

@@ -0,0 +1,28 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-door",
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 13,
+  "digest": "sha256:90f0731ebb2e6d8a7c29e6f1e6f250cb2eb719b6622e5d9e5655281947584d6c",
+  "testsNotRun": {
+    "tests/page/accessible-name-hidden.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/page/channel.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/page/driver.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/page/indicator.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/page/visible-text.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/host/door.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/host/verbs.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/host/shim.spec.ts": "needs jsdom, a development dependency of ACRYL that generated apps do not install; it runs in ACRYL, and verify:scaffolder walks the door in a real browser",
+    "tests/host/loader.spec.ts": "loads the plugin through the real Loader (@deepseek-ai/cordis-plugin-loader), which generated apps do not install"
+  },
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-inspect/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-inspect",
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "vendored": [
     "src",

package/plugins/acryl-kv/plugin.json

@@ -8,5 +8,10 @@
     "@deepseek-ai/cordis": "4.0.4"
   },
   "mount": "it is the port, not a service: a plugin declares inject: ['kv'] and imports the ctx.kv type from '../plugins/acryl-kv/src/cordis.ts'; add acryl-kv-json (a file) or acryl-kv-db (your SQL database) to provide it",
-  "omit": ["src/conformance.ts", "**/*.test.*", "**/*.spec.*", "**/*.case.ts"]
+  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"],
+  "imports": {
+    "#acryl-kv": "acryl-kv/src/index.ts",
+    "#acryl-kv/conformance": "acryl-kv/src/conformance.ts"
+  },
+  "suite": "src/conformance.ts"
 }

package/plugins/acryl-kv/src/conformance.ts

@@ -0,0 +1,226 @@
+/**
+ * The `kv` conformance suite: what every provider of the port must do, as Vitest tests. A provider passes it to be accepted
+ * (`describeKvConformance('acryl-kv-json', open)` in its own tests), so the same cases run on a file and on SQL.
+ */
+
+import { afterEach, describe, expect, it } from 'vitest'
+import type { Kv } from './kv.ts'
+
+/** A fresh, empty store from the provider under test. */
+export interface KvUnderTest {
+  readonly kv: Kv
+  close(): Promise<void>
+  /** Close this store (if it is still open) and open the same storage again, to prove what was written is durable. */
+  reopen(): Promise<KvUnderTest>
+}
+
+export function describeKvConformance(provider: string, open: () => Promise<KvUnderTest>): void {
+  describe(`kv conformance: ${provider}`, () => {
+    const opened: KvUnderTest[] = []
+    const track = (subject: KvUnderTest): KvUnderTest => {
+      opened.push(subject)
+      return subject
+    }
+    const fresh = async (): Promise<Kv> => track(await open()).kv
+    afterEach(async () => {
+      await Promise.all(opened.splice(0).map(subject => subject.close()))
+    })
+
+    it('round-trips null, booleans, numbers, text with unicode, arrays and nested objects', async () => {
+      const kv = await fresh()
+      const values: unknown[] = [null, true, false, 0, -1.5, 9_007_199_254_740_991, '', 'café ✓ 😀', [], [1, [2, [3]]], {}, { a: { b: [1, { c: null }] }, 'ключ': 'значение' }]
+      for (const [index, value] of values.entries()) {
+        await kv.set(`value/${index}`, value)
+        expect(await kv.get(`value/${index}`), JSON.stringify(value)).toEqual(value)
+      }
+    })
+
+    it('answers get with undefined for a missing key, and overwrites on set', async () => {
+      const kv = await fresh()
+      expect(await kv.get('missing')).toBeUndefined()
+      await kv.set('k', { n: 1 })
+      await kv.set('k', { n: 2 })
+      expect(await kv.get('k')).toEqual({ n: 2 })
+    })
+
+    it('deletes a key, and a missing key is not an error', async () => {
+      const kv = await fresh()
+      await kv.set('k', 1)
+      await kv.delete('k')
+      expect(await kv.get('k')).toBeUndefined()
+      await expect(kv.delete('k')).resolves.toBeUndefined()
+      await expect(kv.delete('never-existed')).resolves.toBeUndefined()
+    })
+
+    it('stores a null value as null, apart from a missing key', async () => {
+      const kv = await fresh()
+      await kv.set('k', null)
+      expect(await kv.get('k')).toBeNull()
+      expect(await kv.list()).toEqual(['k'])
+    })
+
+    it('lists keys sorted by code point, with an optional prefix', async () => {
+      const kv = await fresh()
+      for (const key of ['b', 'a/2', 'a/10', 'a/1', 'ab', 'B', 'a']) await kv.set(key, key)
+      expect(await kv.list()).toEqual(['B', 'a', 'a/1', 'a/10', 'a/2', 'ab', 'b'])
+      expect(await kv.list('a/')).toEqual(['a/1', 'a/10', 'a/2'])
+      expect(await kv.list('a')).toEqual(['a', 'a/1', 'a/10', 'a/2', 'ab'])
+      expect(await kv.list('')).toEqual(['B', 'a', 'a/1', 'a/10', 'a/2', 'ab', 'b'])
+      expect(await kv.list('nothing')).toEqual([])
+      expect(await kv.list(undefined)).toEqual(await kv.list())
+    })
+
+    it('orders astral characters after the rest of the basic plane, as code points', async () => {
+      const kv = await fresh()
+      for (const key of ['\u{1F600}', '～', 'z', '']) await kv.set(key, 1)
+      expect(await kv.list()).toEqual(['z', '', '～', '\u{1F600}'])
+    })
+
+    it('treats % _ \\ and letter case in a prefix as plain characters', async () => {
+      const kv = await fresh()
+      for (const key of ['100%', '100x', 'a_b', 'axb', 'Abc', 'abc', 'back\\slash', 'backXslash']) await kv.set(key, 1)
+      expect(await kv.list('100%')).toEqual(['100%'])
+      expect(await kv.list('a_')).toEqual(['a_b'])
+      expect(await kv.list('ab')).toEqual(['abc'])
+      expect(await kv.list('Ab')).toEqual(['Abc'])
+      expect(await kv.list('back\\')).toEqual(['back\\slash'])
+      expect(await kv.list('\u{1F600}')).toEqual([])
+    })
+
+    it('updates a missing key from undefined, and a present one from its value, resolving the new value', async () => {
+      const kv = await fresh()
+      expect(await kv.update<number>('n', current => (current ?? 0) + 1)).toBe(1)
+      expect(await kv.update<number>('n', current => (current ?? 0) + 10)).toBe(11)
+      expect(await kv.get('n')).toBe(11)
+      expect(await kv.update<string[]>('list', current => [...(current ?? []), 'a'])).toEqual(['a'])
+    })
+
+    it('counts fifty concurrent updates to exactly fifty', async () => {
+      const kv = await fresh()
+      await Promise.all(Array.from({ length: 50 }, () => kv.update<number>('counter', current => (current ?? 0) + 1)))
+      expect(await kv.get('counter')).toBe(50)
+    })
+
+    it('keeps updates of different keys independent, and a set between two updates in order', async () => {
+      const kv = await fresh()
+      const results = await Promise.all([
+        kv.update<number>('a', current => (current ?? 0) + 1),
+        kv.set('a', 100),
+        kv.update<number>('a', current => (current ?? 0) + 1),
+        kv.update<number>('b', current => (current ?? 0) + 5),
+      ])
+      expect(results[0]).toBe(1)
+      expect(results[2]).toBe(101)
+      expect(await kv.get('a')).toBe(101)
+      expect(await kv.get('b')).toBe(5)
+    })
+
+    it('leaves the value as it was when the update callback throws, and rejects with its error', async () => {
+      const kv = await fresh()
+      await kv.set('k', 'before')
+      const failure = new Error('stop')
+      await expect(kv.update('k', () => { throw failure })).rejects.toBe(failure)
+      expect(await kv.get('k')).toBe('before')
+      await expect(kv.update('absent', () => { throw failure })).rejects.toBe(failure)
+      expect(await kv.get('absent')).toBeUndefined()
+    })
+
+    it('leaves the value as it was when the update returns something that is not JSON', async () => {
+      const kv = await fresh()
+      await kv.set('k', 'before')
+      await expect(kv.update('k', () => undefined as never)).rejects.toThrow(TypeError)
+      await expect(kv.update('k', () => Number.NaN as never)).rejects.toThrow(TypeError)
+      expect(await kv.get('k')).toBe('before')
+    })
+
+    it('rejects an update callback that returns a promise, with a message that says what to do, and keeps the value', async () => {
+      const kv = await fresh()
+      await kv.set('k', 1)
+      const asynchronous = (async () => 2) as unknown as (current: number | undefined) => number
+      await expect(kv.update<number>('k', asynchronous)).rejects.toThrow(/synchronous/u)
+      expect(await kv.get('k')).toBe(1)
+      await kv.update<number>('k', current => (current ?? 0) + 1)
+      expect(await kv.get('k')).toBe(2)
+    })
+
+    it('refuses an empty or non-string key on every call, and writes nothing', async () => {
+      const kv = await fresh()
+      for (const key of ['', 1, null, undefined, {}] as unknown as string[]) {
+        await expect(kv.get(key)).rejects.toThrow(TypeError)
+        await expect(kv.set(key, 1)).rejects.toThrow(TypeError)
+        await expect(kv.update(key, () => 1)).rejects.toThrow(TypeError)
+        await expect(kv.delete(key)).rejects.toThrow(TypeError)
+      }
+      expect(await kv.list()).toEqual([])
+    })
+
+    it('refuses a value that is not JSON with a TypeError, and writes nothing', async () => {
+      const kv = await fresh()
+      const circular: Record<string, unknown> = {}
+      circular.self = circular
+      for (const value of [undefined, () => 1, Symbol('s'), 1n, Number.NaN, Number.POSITIVE_INFINITY, circular, { deep: [Number.NEGATIVE_INFINITY] }]) {
+        await expect(kv.set('k', value), String(value)).rejects.toThrow(TypeError)
+      }
+      expect(await kv.list()).toEqual([])
+      await kv.set('k', 'kept')
+      await expect(kv.set('k', undefined)).rejects.toThrow(TypeError)
+      expect(await kv.get('k')).toBe('kept')
+    })
+
+    it('hands out copies: changing what get returned, or the value after set, changes nothing stored', async () => {
+      const kv = await fresh()
+      const original = { list: [1, 2], nested: { n: 1 } }
+      await kv.set('k', original)
+      original.list.push(3)
+      const first = await kv.get<typeof original>('k')
+      expect(first).toEqual({ list: [1, 2], nested: { n: 1 } })
+      first!.nested.n = 99
+      expect(await kv.get('k')).toEqual({ list: [1, 2], nested: { n: 1 } })
+      const updated = await kv.update<typeof original>('k', current => {
+        current!.list.push(4)
+        return current!
+      })
+      updated.list.push(5)
+      expect(await kv.get('k')).toEqual({ list: [1, 2, 4], nested: { n: 1 } })
+    })
+
+    it('stores a value of a megabyte', async () => {
+      const kv = await fresh()
+      const big = 'x'.repeat(1024 * 1024)
+      await kv.set('big', { big })
+      expect((await kv.get<{ big: string }>('big'))?.big.length).toBe(big.length)
+    })
+
+    it('keeps what was written across close and reopen, and keeps a deleted key deleted', async () => {
+      const first = track(await open())
+      await first.kv.set('a', { n: 1 })
+      await first.kv.set('b', 'two')
+      await first.kv.update<number>('count', current => (current ?? 0) + 1)
+      await first.kv.set('gone', 1)
+      await first.kv.delete('gone')
+      const second = track(await first.reopen())
+      expect(await second.kv.list()).toEqual(['a', 'b', 'count'])
+      expect(await second.kv.get('a')).toEqual({ n: 1 })
+      expect(await second.kv.get('count')).toBe(1)
+      expect(await second.kv.get('gone')).toBeUndefined()
+    })
+
+    it('rejects calls after close, and closing twice does nothing', async () => {
+      const subject = track(await open())
+      await subject.kv.set('k', 1)
+      await subject.close()
+      await subject.close()
+      await expect(subject.kv.get('k')).rejects.toThrow()
+      await expect(subject.kv.set('k', 2)).rejects.toThrow()
+    })
+
+    it('waits for writes still in flight when it closes', async () => {
+      const subject = track(await open())
+      const writes = Array.from({ length: 20 }, (_, index) => subject.kv.set(`k${String(index).padStart(2, '0')}`, index))
+      await subject.close()
+      await Promise.all(writes)
+      const again = track(await subject.reopen())
+      expect(await again.kv.list()).toHaveLength(20)
+    })
+  })
+}

package/plugins/acryl-kv/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-kv",
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "vendored": [
     "src",

package/plugins/acryl-kv-db/plugin.json

@@ -9,5 +9,8 @@
     "@deepseek-ai/schemastery": "3.18.4"
   },
   "mount": "mount it after acryl-db-sqlite: root.plugin(kvDb, {}); it waits for db and provides the same kv as acryl-kv-json",
-  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"]
+  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"],
+  "imports": {
+    "#acryl-kv-db": "acryl-kv-db/src/index.ts"
+  }
 }

package/plugins/acryl-kv-db/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-kv-db",
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "vendored": [
     "src",

package/plugins/acryl-kv-json/plugin.json

@@ -9,5 +9,8 @@
     "@deepseek-ai/schemastery": "3.18.4"
   },
   "mount": "mount it after instance: root.plugin(kvJson, {}) (the file is kv.json in the app home, or set path); then a plugin that declares inject: ['kv'] calls await ctx.kv.set('theme', 'dark') and ctx.kv.update('visits', (n) => (n ?? 0) + 1)",
-  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"]
+  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"],
+  "imports": {
+    "#acryl-kv-json": "acryl-kv-json/src/index.ts"
+  }
 }

package/plugins/acryl-kv-json/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-kv-json",
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "vendored": [
     "src",

package/plugins/acryl-node-server/src/adapter/listener.ts

@@ -89,6 +89,11 @@ const drainIncoming = (incoming: IncomingMessage | Http2ServerRequest): void =>
     }
   }
 
+  // A body reader the app stopped using (Readable.toWeb behind bodyLimit, for one) still listens for
+  // data and pauses the request again as soon as its queue is full, so the drain would stall after
+  // one chunk and the timer would close a socket with unread data, which the kernel answers with RST.
+  // Nobody reads the body any more, so the drain is the only data listener.
+  incoming.removeAllListeners('data')
   incoming.on('data', onData)
   incoming.on('end', cleanup)
   incoming.on('error', cleanup)

package/plugins/acryl-node-server/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-node-server",
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "vendored": [
     "src",
@@ -10,7 +10,7 @@
     "LICENSE"
   ],
   "rewrittenSpecifiers": 31,
-  "digest": "sha256:e92c0621600e414cffd3e063c117a887410de53113ac4f5966231b419ed92da1",
+  "digest": "sha256:4142980d289b36c661e572ecbb5f19f06f0c95fc277ce4dca9b543d366c291e8",
   "testsNotRun": {
     "tests/client-modules.spec.ts": "links typescript from the plugin's own node_modules (ACRYL's workspace layout); clientModules and build-client are exercised here by the templates' tests and verify:scaffolder",
     "tests/register.spec.ts": "links typescript from the plugin's own node_modules (ACRYL's workspace layout); the hook is exercised here by the templates' own .tsx tests and verify:scaffolder"

package/plugins/acryl-router/src/service.ts

@@ -198,6 +198,9 @@ export class Router extends Service {
       }
       ;(handler as unknown as Record<string, unknown>)[COMPOSED_HANDLER] = inner
       tagged.on(route.method, route.path, handler)
+      // `on` registers under the base path of `tagged` (`/`), which would hide the prefix of a nested app from `basePath(c)`; keep the route's own.
+      const registered = tagged.routes.at(-1)
+      if (registered !== undefined) registered.basePath = route.basePath
     }
     return mount
   }

package/plugins/acryl-router/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router",
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "vendored": [
     "src",
@@ -10,7 +10,7 @@
     "LICENSE"
   ],
   "rewrittenSpecifiers": 6,
-  "digest": "sha256:5f07e873992fa2f0a178e029a1fe3d8c99cb4ce3ae8c07445d75431f95125417",
+  "digest": "sha256:f9679acf23d0a647a3f8bf9bb3cb9107eb03d25192ab401506e3a4ee570e305e",
   "testsNotRun": {
     "tests/loader.spec.ts": "loads the built lib/ entry through the real Loader; the library ships source and has no build"
   },