acrylblends 0.0.0-stage → 0.3.0

package/plugins/acryl-router-http/src/index.ts

@@ -0,0 +1,63 @@
+/**
+ * The Web adapter for `acryl-router` (spec 046, milestone M2). A plugin that owns routes on the router asks for a path
+ * prefix to be served over HTTP: `ctx.routerHttp.mount('/api/market')` claims that prefix on the DSH `webServer` and every
+ * request under it is run through `router.fetch`. The TUI and Desktop do not need this: they call `router.fetch` directly.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { RouterHttpService } from '../../acryl-router/src/index.ts'
+import { Context, Service } from '@deepseek-ai/cordis'
+import { serve } from './serve.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-router-http'
+
+/** Hard requirements: both services must exist, otherwise this plugin stays PENDING. */
+export const inject = ['router', 'webServer']
+
+/**
+ * The slice of the DSH `webServer` this adapter uses, as its own port: a prefix claim that returns its remover. The service
+ * is read by name, so this package imports nothing from the DeepSeek Harness (the layout gate keeps that count falling).
+ */
+export interface WebServerPort {
+  register(route: {
+    readonly kind: 'prefix'
+    readonly path: string
+    readonly handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+  }): () => void
+}
+
+const PREFIX_PATTERN = /^\/[A-Za-z0-9._~\-/]*[A-Za-z0-9._~-]$/
+
+export class RouterHttp extends Service implements RouterHttpService {
+  private readonly router: Context['router']
+  private readonly web: WebServerPort
+
+  constructor(ctx: Context) {
+    super(ctx, 'routerHttp')
+    this.router = ctx.router
+    this.web = ctx.get('webServer') as WebServerPort
+  }
+
+  /**
+   * Serve `prefix` and everything below it through the router. Returns a remover; the mount also goes away when the
+   * calling plugin unloads. A prefix another route already claims throws, as the webServer treats it as misconfiguration.
+   */
+  mount(prefix: string): () => void {
+    if (!PREFIX_PATTERN.test(prefix)) throw new TypeError(`acryl-router-http: "${prefix}" is not a mountable path prefix`)
+    const remove = this.web.register({
+      kind: 'prefix',
+      path: prefix,
+      handler: (req, res) => serve(this.router, req, res),
+    })
+    this.ctx.effect(() => () => { remove() }, `acryl-router-http: mount ${prefix}`)
+    return remove
+  }
+}
+
+export function apply(ctx: Context): void {
+  new RouterHttp(ctx)
+}
+
+export { serve, type FetchRouter } from './serve.ts'
+export { sendResponse, toRequest } from './bridge.ts'

package/plugins/acryl-router-http/src/serve.ts

@@ -0,0 +1,24 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { sendResponse, toRequest } from './bridge.ts'
+
+/** The slice of the router this adapter needs; `acryl-router`'s `Router` satisfies it. */
+export interface FetchRouter {
+  fetch(request: Request, connection?: { readonly remoteAddress?: string | undefined, readonly localPort?: number | undefined }): Promise<Response>
+}
+
+/**
+ * Serve one node request through the router and write the result. The request's abort signal fires when the client
+ * disconnects before the response finished; the socket's peer address and local port travel as connection info, never in the request.
+ */
+export async function serve(router: FetchRouter, req: IncomingMessage, res: ServerResponse): Promise<void> {
+  const controller = new AbortController()
+  res.once('close', () => { if (!res.writableFinished) controller.abort() })
+  const method = (req.method ?? 'GET').toUpperCase()
+  let response: Response
+  try {
+    response = await router.fetch(toRequest(req, controller.signal), { remoteAddress: req.socket.remoteAddress, localPort: req.socket.localPort })
+  } catch {
+    response = new Response('Internal Server Error', { status: 500 })
+  }
+  await sendResponse(res, response, method)
+}

package/plugins/acryl-router-http/tests/adapter.spec.ts

@@ -0,0 +1,170 @@
+/**
+ * The Web adapter against the real DSH `webServer` listening on a loopback port: a plugin mounts a prefix, requests
+ * travel over real HTTP into `router.fetch`, and the lifecycle (PENDING, unload, reload) is observed the way a browser
+ * would see it. The router is the built `acryl-router` entry, as production loads it.
+ */
+
+import { Context, type FiberState } from '@deepseek-ai/cordis'
+import WebServer from '@deepseek-ai/dsh-host-webserver'
+import { apply as routerApply, name as routerName } from '../../acryl-router/src/index.ts'
+import { afterEach, describe, expect, it } from 'vitest'
+import type { RouterHttpService } from '../../acryl-router/src/index.ts'
+import { apply, inject, name } from '../src/index.ts'
+
+const PENDING = 0 as FiberState.PENDING
+const ACTIVE = 2 as FiberState.ACTIVE
+
+const contexts: Context[] = []
+const settle = (ms = 0): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
+afterEach(async () => {
+  while (contexts.length > 0) await contexts.pop()?.fiber.dispose()
+})
+
+async function until(check: () => boolean, label: string): Promise<void> {
+  for (let i = 0; i < 300; i += 1) { if (check()) return; await settle(10) }
+  throw new Error(`timed out waiting for: ${label}`)
+}
+
+const adapter = { name, inject, apply }
+const router = { name: routerName, apply: routerApply }
+
+/** A whole stack on one root context: webServer on an OS-assigned port, the router, and the adapter. */
+async function stack(): Promise<{ ctx: Context, base: () => string }> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  ctx.plugin(WebServer, { host: '127.0.0.1', port: 0 } as never)
+  ctx.plugin(router, { trailingSlash: 'strict' })
+  ctx.plugin(adapter)
+  await until(() => (ctx as unknown as { webServer?: { port: number } }).webServer?.port !== undefined && ctx.routerHttp !== undefined, 'the stack to start')
+  return { ctx, base: () => `http://127.0.0.1:${String((ctx as unknown as { webServer: { port: number } }).webServer.port)}` }
+}
+
+function demo(prefix: string, extra?: (ctx: Context) => void) {
+  return {
+    name: `demo${prefix.replaceAll('/', '-')}`,
+    inject: ['router', 'routerHttp'],
+    apply(ctx: Context): void {
+      ctx.routerHttp.mount(prefix)
+      ctx.router.get(`${prefix}/hello/:who`, c => c.json({ hello: c.params['who'], q: c.url.searchParams.get('q'), host: c.req.headers.get('host') !== null }))
+      ctx.router.post(`${prefix}/echo`, async c => c.json({ got: await c.req.text(), type: c.req.headers.get('content-type') }, 201))
+      ctx.router.get(`${prefix}/cookies`, () => {
+        const headers = new Headers()
+        headers.append('set-cookie', 'a=1; Path=/')
+        headers.append('set-cookie', 'b=2; Path=/')
+        return new Response('ok', { headers })
+      })
+      ctx.router.get(`${prefix}/stream`, () => new Response(new ReadableStream({
+        start(controller) { controller.enqueue(new TextEncoder().encode('one,')); controller.enqueue(new TextEncoder().encode('two')); controller.close() },
+      })))
+      ctx.router.get(`${prefix}/peer`, c => c.json({ remote: c.connection.remoteAddress ?? null, localPort: c.connection.localPort ?? null }))
+      extra?.(ctx)
+    },
+  }
+}
+
+describe('acryl-router-http against a real webServer', () => {
+  it('serves a mounted prefix over HTTP: params, query, JSON, status', async () => {
+    const { ctx, base } = await stack()
+    ctx.plugin(demo('/api/demo'))
+    await settle(20)
+    const response = await fetch(`${base()}/api/demo/hello/zed%20x?q=1`)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toContain('application/json')
+    expect(await response.json()).toEqual({ hello: 'zed x', q: '1', host: true })
+  })
+
+  it('passes the socket peer address as connection info, not as part of the request', async () => {
+    const { ctx, base } = await stack()
+    ctx.plugin(demo('/api/demo'))
+    await settle(20)
+    const body = await (await fetch(`${base()}/api/demo/peer`)).json() as { remote: string | null, localPort: number | null }
+    expect(['127.0.0.1', '::ffff:127.0.0.1']).toContain(body.remote)
+    expect(body.localPort).toBe(Number(new URL(base()).port))
+  })
+
+  it('streams a request body into the handler and keeps status and headers on the way out', async () => {
+    const { ctx, base } = await stack()
+    ctx.plugin(demo('/api/demo'))
+    await settle(20)
+    const response = await fetch(`${base()}/api/demo/echo`, { method: 'POST', body: 'payload', headers: { 'content-type': 'text/plain' } })
+    expect(response.status).toBe(201)
+    expect(await response.json()).toEqual({ got: 'payload', type: 'text/plain' })
+  })
+
+  it('keeps repeated set-cookie headers separate and streams a response body', async () => {
+    const { ctx, base } = await stack()
+    ctx.plugin(demo('/api/demo'))
+    await settle(20)
+    const cookies = await fetch(`${base()}/api/demo/cookies`)
+    expect(cookies.headers.getSetCookie()).toEqual(['a=1; Path=/', 'b=2; Path=/'])
+    expect(await (await fetch(`${base()}/api/demo/stream`)).text()).toBe('one,two')
+  })
+
+  it('answers the router\'s 404 and 405 below the mount, and answers HEAD without a body', async () => {
+    const { ctx, base } = await stack()
+    ctx.plugin(demo('/api/demo'))
+    await settle(20)
+    const missing = await fetch(`${base()}/api/demo/none`)
+    expect(missing.status).toBe(404)
+    expect(await missing.text()).toBe('Not Found')
+    expect((await fetch(`${base()}/api/demo/echo`)).status).toBe(405)
+    const head = await fetch(`${base()}/api/demo/hello/a`, { method: 'HEAD' })
+    expect(head.status).toBe(200)
+    expect(head.headers.get('content-type')).toContain('application/json')
+    expect(await head.text()).toBe('')
+  })
+
+  it('aborts the handler signal when the HTTP client disconnects', async () => {
+    const { ctx, base } = await stack()
+    let aborted = false
+    ctx.plugin(demo('/api/demo', c => {
+      c.router.get('/api/demo/slow', async r => {
+        await new Promise<void>((_resolve, reject) => { r.signal.addEventListener('abort', () => { aborted = true; reject(new Error('aborted')) }, { once: true }) })
+        return r.text('never')
+      })
+    }))
+    await settle(20)
+    const controller = new AbortController()
+    const pending = fetch(`${base()}/api/demo/slow`, { signal: controller.signal }).catch(() => undefined)
+    await settle(50)
+    controller.abort()
+    await pending
+    await until(() => aborted, 'the handler to see the disconnect')
+  })
+
+  it('stops serving the prefix when the owning plugin unloads, and serves it again on reload, fifty times', async () => {
+    const { ctx, base } = await stack()
+    for (let i = 0; i < 50; i += 1) {
+      const fiber = ctx.plugin(demo('/api/demo'))
+      await settle(5)
+      expect((await fetch(`${base()}/api/demo/hello/a`)).status).toBe(200)
+      await fiber.dispose()
+      await settle(5)
+      // Unmounted: the webServer has no fallback in this stack, so it answers its own empty 404, not the router's body.
+      const gone = await fetch(`${base()}/api/demo/hello/a`)
+      expect(gone.status).toBe(404)
+      expect(await gone.text()).toBe('')
+    }
+    expect(ctx.router.size).toBe(0)
+  })
+
+  it('stays PENDING while webServer is missing and activates when it appears', async () => {
+    const ctx = new Context()
+    contexts.push(ctx)
+    ctx.plugin(router, { trailingSlash: 'strict' })
+    const fiber = ctx.plugin(adapter)
+    await settle(20)
+    expect(fiber.state).toBe(PENDING)
+    ctx.plugin(WebServer, { host: '127.0.0.1', port: 0 } as never)
+    await until(() => fiber.state === ACTIVE, 'the adapter to activate')
+  })
+
+  it('refuses a prefix that is not a clean path and a prefix another plugin already mounted', async () => {
+    const { ctx } = await stack()
+    const http: RouterHttpService = ctx.routerHttp
+    expect(() => http.mount('no-slash')).toThrow(/mountable/)
+    expect(() => http.mount('/trailing/')).toThrow(/mountable/)
+    http.mount('/api/once')
+    expect(() => http.mount('/api/once')).toThrow(/duplicate/)
+  })
+})

package/plugins/acryl-router-http/tests/stream.spec.ts

@@ -0,0 +1,133 @@
+/**
+ * Server-sent events end to end (spec 046, M5): the actual DSH `webServer`, the router, the HTTP adapter and the state
+ * service. A browser-shaped `fetch` reads the stream; a change in the Host reaches it; a disconnect and a plugin unload both
+ * end it and leave nothing subscribed.
+ */
+
+import { request as httpRequest } from 'node:http'
+import { Context } from '@deepseek-ai/cordis'
+import WebServer from '@deepseek-ai/dsh-host-webserver'
+import { apply as routerApply, name as routerName } from '../../acryl-router/src/index.ts'
+import { apply as stateApply, name as stateName } from '../../acryl-state/src/index.ts'
+import { afterEach, describe, expect, it } from 'vitest'
+import { apply as httpApply, inject as httpInject, name as httpName } from '../src/index.ts'
+
+const contexts: Context[] = []
+const settle = (ms = 0): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
+afterEach(async () => {
+  while (contexts.length > 0) await contexts.pop()?.fiber.dispose()
+})
+
+async function until(check: () => boolean, label: string): Promise<void> {
+  for (let i = 0; i < 300; i += 1) { if (check()) return; await settle(10) }
+  throw new Error(`timed out waiting for: ${label}`)
+}
+
+async function stack(): Promise<{ ctx: Context, base: string }> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  ctx.plugin(WebServer, { host: '127.0.0.1', port: 0 } as never)
+  ctx.plugin({ name: routerName, apply: routerApply }, { trailingSlash: 'strict' })
+  ctx.plugin({ name: httpName, inject: httpInject, apply: httpApply })
+  ctx.plugin({ name: stateName, apply: stateApply })
+  const web = ctx as unknown as { webServer?: { port: number } }
+  await until(() => web.webServer?.port !== undefined && (ctx as unknown as { routerHttp?: unknown }).routerHttp !== undefined && (ctx as unknown as { state?: unknown }).state !== undefined, 'the stack')
+  await settle(30)
+  return { ctx, base: `http://127.0.0.1:${String(web.webServer!.port)}` }
+}
+
+/** Collect SSE records from a fetch response until `count` arrived. */
+async function read(reader: ReadableStreamDefaultReader<Uint8Array>, count: number): Promise<string[]> {
+  const decoder = new TextDecoder()
+  let buffer = ''
+  const out: string[] = []
+  while (out.length < count) {
+    const { done, value } = await reader.read()
+    if (done) break
+    buffer += decoder.decode(value, { stream: true })
+    for (let at = buffer.indexOf('\n\n'); at !== -1; at = buffer.indexOf('\n\n')) {
+      out.push(buffer.slice(0, at))
+      buffer = buffer.slice(at + 2)
+    }
+  }
+  return out
+}
+
+describe('server-sent events through the real stack', () => {
+  it('streams the value now and each change to a real HTTP client, with the stream headers', async () => {
+    const { ctx, base } = await stack()
+    const cell = ctx.state.cell<{ n: number }>('app.counter', { n: 0 })
+    const response = await fetch(`${base}/api/state/app.counter/events`)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toContain('text/event-stream')
+    const reader = response.body!.getReader()
+    const first = read(reader, 3)
+    await settle(20)
+    cell.set({ n: 1 })
+    cell.set({ n: 2 })
+    expect(await first).toEqual(['event: value\ndata: {"n":0}', 'event: value\ndata: {"n":1}', 'event: value\ndata: {"n":2}'])
+    await reader.cancel()
+  })
+
+  it('stops pushing to a client that disconnected: the cell keeps no subscriber for it', async () => {
+    const { ctx, base } = await stack()
+    const cell = ctx.state.cell<number>('app.n', 0)
+    const controller = new AbortController()
+    const response = await fetch(`${base}/api/state/app.n/events`, { signal: controller.signal })
+    const reader = response.body!.getReader()
+    await read(reader, 1)
+    let seenByProbe = 0
+    // While connected, a change reaches the stream; count the cell's own subscribers through a counting wrapper.
+    controller.abort()
+    await reader.cancel().catch(() => undefined)
+    await settle(50)
+    const stop = cell.subscribe(() => { seenByProbe += 1 })
+    cell.set(1)
+    stop()
+    expect(seenByProbe).toBe(1)
+    // The disconnect released the stream: the router has no request left in flight to abort at disposal.
+    const started = Date.now()
+    await ctx.fiber.dispose()
+    contexts.length = 0
+    expect(Date.now() - started).toBeLessThan(1500)
+  })
+
+  it('ends an open stream when the state plugin unloads', async () => {
+    const { ctx, base } = await stack()
+    ctx.state.cell<number>('app.n', 0)
+    const response = await fetch(`${base}/api/state/app.n/events`)
+    const reader = response.body!.getReader()
+    await read(reader, 1)
+    const ended = reader.read()
+    const routerFiber = [...[...ctx.registry.values()].find(runtime => runtime.name === routerName)!.fibers][0]!
+    await routerFiber.dispose()
+    await expect(ended).resolves.toMatchObject({ done: true })
+  })
+})
+
+describe('the loopback guard over real HTTP', () => {
+  /** A raw request, so the test chooses the Host header (fetch would set its own). */
+  function raw(port: number, path: string, headers: Record<string, string>): Promise<{ status: number, body: string }> {
+    return new Promise((resolve, reject) => {
+      const req = httpRequest({ host: '127.0.0.1', port, path, headers }, res => {
+        let body = ''
+        res.on('data', chunk => { body += String(chunk) })
+        res.on('end', () => { resolve({ status: res.statusCode ?? 0, body }) })
+      })
+      req.on('error', reject)
+      req.end()
+    })
+  }
+
+  it('serves the state routes to this machine and refuses a request that names another host or is marked cross-site', async () => {
+    const { ctx, base } = await stack()
+    ctx.state.cell<number>('app.n', 3)
+    const port = Number(new URL(base).port)
+    const ok = await raw(port, '/api/state/app.n', { host: `127.0.0.1:${String(port)}` })
+    expect(ok.status).toBe(200)
+    expect(JSON.parse(ok.body)).toEqual({ key: 'app.n', value: 3 })
+    expect((await raw(port, '/api/state/app.n', { host: 'evil.example' })).status).toBe(403)
+    expect((await raw(port, '/api/state/app.n', { host: `127.0.0.1:${String(port + 1)}` })).status).toBe(403)
+    expect((await raw(port, '/api/state/app.n', { host: `127.0.0.1:${String(port)}`, 'sec-fetch-site': 'cross-site' })).status).toBe(403)
+  })
+})

package/plugins/acryl-router-http/tests/surfaces.spec.ts

@@ -0,0 +1,99 @@
+/**
+ * One plugin, two compositions (spec 046, M3): the same `apply` runs in a Web or Desktop composition (the DSH webServer,
+ * the router and the HTTP adapter) and in a terminal composition (the router alone, no server at all). The routes are
+ * registered once, in `apply`; serving them over HTTP is the optional part, requested through an inner `inject`. The
+ * assertions compare what a browser receives with what the terminal's in-process call receives.
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import WebServer from '@deepseek-ai/dsh-host-webserver'
+import { apply as routerApply, name as routerName } from '../../acryl-router/src/index.ts'
+import { afterEach, describe, expect, it } from 'vitest'
+import { apply as httpApply, inject as httpInject, name as httpName } from '../src/index.ts'
+
+const contexts: Context[] = []
+const settle = (ms = 0): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
+afterEach(async () => {
+  while (contexts.length > 0) await contexts.pop()?.fiber.dispose()
+})
+
+async function until(check: () => boolean, label: string): Promise<void> {
+  for (let i = 0; i < 300; i += 1) { if (check()) return; await settle(10) }
+  throw new Error(`timed out waiting for: ${label}`)
+}
+
+/** A capability as a plugin author writes it: routes in `apply`, HTTP only if an adapter happens to be present. */
+const notes = {
+  name: 'notes-demo',
+  inject: ['router'],
+  apply(ctx: Context): void {
+    const store = new Map<string, string>()
+    ctx.router.post('/api/notes/:id', async c => {
+      const text = await c.req.text()
+      store.set(c.params['id'] ?? '', text)
+      return c.json({ id: c.params['id'], saved: text.length }, 201)
+    })
+    ctx.router.get('/api/notes/:id', c => {
+      const text = store.get(c.params['id'] ?? '')
+      return text === undefined ? c.json({ error: 'not found' }, 404) : c.json({ id: c.params['id'], text })
+    })
+    ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/api/notes') })
+  },
+}
+
+/** Web or Desktop: a loopback webServer, the router and the adapter. */
+async function webComposition(): Promise<{ ctx: Context, base: string }> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  ctx.plugin(WebServer, { host: '127.0.0.1', port: 0 } as never)
+  ctx.plugin({ name: routerName, apply: routerApply }, { trailingSlash: 'strict' })
+  ctx.plugin({ name: httpName, inject: httpInject, apply: httpApply })
+  const web = ctx as unknown as { webServer?: { port: number } }
+  await until(() => web.webServer?.port !== undefined && (ctx as unknown as { routerHttp?: unknown }).routerHttp !== undefined, 'the web composition')
+  ctx.plugin(notes)
+  await settle(30)
+  return { ctx, base: `http://127.0.0.1:${String(web.webServer!.port)}` }
+}
+
+/** Terminal: the router only. No server, no adapter, nothing listening. */
+async function terminalComposition(): Promise<Context> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  ctx.plugin({ name: routerName, apply: routerApply }, { trailingSlash: 'strict' })
+  await settle(20)
+  ctx.plugin(notes)
+  await settle(20)
+  return ctx
+}
+
+async function snapshot(response: Response): Promise<{ status: number, type: string | null, body: unknown }> {
+  return { status: response.status, type: response.headers.get('content-type'), body: await response.json() }
+}
+
+describe('the same capability on every surface', () => {
+  it('answers a browser over HTTP and the terminal in process with the same status, headers and body', async () => {
+    const web = await webComposition()
+    const terminal = await terminalComposition()
+
+    const viaHttp = [
+      await snapshot(await fetch(`${web.base}/api/notes/a`)),
+      await snapshot(await fetch(`${web.base}/api/notes/a`, { method: 'POST', body: 'hello' })),
+      await snapshot(await fetch(`${web.base}/api/notes/a`)),
+    ]
+    const router = (terminal as unknown as { router: { fetch(request: Request): Promise<Response> } }).router
+    const inProcess = [
+      await snapshot(await router.fetch(new Request('http://acryl.test/api/notes/a'))),
+      await snapshot(await router.fetch(new Request('http://acryl.test/api/notes/a', { method: 'POST', body: 'hello' }))),
+      await snapshot(await router.fetch(new Request('http://acryl.test/api/notes/a'))),
+    ]
+
+    expect(inProcess).toEqual(viaHttp)
+    expect(viaHttp.map(step => step.status)).toEqual([404, 201, 200])
+  })
+
+  it('opens no socket in the terminal composition: nothing in that context is a server', async () => {
+    const terminal = await terminalComposition()
+    expect((terminal as unknown as { webServer?: unknown }).webServer).toBeUndefined()
+    expect((terminal as unknown as { routerHttp?: unknown }).routerHttp).toBeUndefined()
+  })
+})

package/plugins/acryl-router-http/upstream.json

@@ -0,0 +1,22 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-router-http",
+    "commit": "11fed295161c0282d144b5ac62616988b58d8189"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 6,
+  "digest": "sha256:6a79e85a11bf61a13604736ef9776f878a024ef19e1282481bdfe13343916bc4",
+  "testsNotRun": {
+    "tests/adapter.spec.ts": "needs @deepseek-ai/dsh-host-webserver (the DSH web server); acryl-node-server has its own tests",
+    "tests/stream.spec.ts": "needs @deepseek-ai/dsh-host-webserver (the DSH web server)",
+    "tests/surfaces.spec.ts": "needs @deepseek-ai/dsh-host-webserver (the DSH web server)"
+  },
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-state/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebBoxes s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/acryl-state/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "acryl-state",
+  "description": "Observable cells and derived cells, shared state with JSON and server-sent event routes on the router. Vendored from ACRYL.",
+  "requires": ["acryl-router"],
+  "inject": ["router"],
+  "provides": ["state"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "mount": "root.plugin(state); ctx.state.cell('todos.count', 0), then count.update((n) => n + 1)",
+  "omit": ["src/react.ts"]
+}

package/plugins/acryl-state/src/cell.ts

@@ -0,0 +1,67 @@
+/**
+ * Observable cells: the reactive core of the state service, with no Cordis and no DOM. A cell holds one value, tells its
+ * subscribers when it changes, and can be derived from other cells. The shape is a writable cell and a derived cell
+ * (spec 046, M5): small enough to read in one sitting, and the same cell serves a React hook, a terminal component and a
+ * server-sent stream.
+ */
+
+export type Listener<T> = (value: T, previous: T) => void
+
+export interface ReadonlyCell<T> {
+  readonly key: string
+  get(): T
+  /** Call `listener` after every change (never for a set to an equal value). Returns the unsubscribe function. */
+  subscribe(listener: Listener<T>): () => void
+}
+
+export interface Cell<T> extends ReadonlyCell<T> {
+  set(value: T): void
+  update(change: (current: T) => T): void
+}
+
+type ErrorSink = (error: unknown) => void
+
+/** A writable cell. `report` receives anything a listener throws; one failing listener never blocks the others. */
+export function createCell<T>(key: string, initial: T, report: ErrorSink = () => undefined): Cell<T> {
+  let value = initial
+  const listeners = new Set<Listener<T>>()
+  const set = (next: T): void => {
+    if (Object.is(next, value)) return
+    const previous = value
+    value = next
+    for (const listener of [...listeners]) {
+      try { listener(next, previous) } catch (error) { report(error) }
+    }
+  }
+  return {
+    key,
+    get: () => value,
+    set,
+    update: change => { set(change(value)) },
+    subscribe: listener => {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+  }
+}
+
+type Values<D extends readonly ReadonlyCell<unknown>[]> = { [K in keyof D]: D[K] extends ReadonlyCell<infer V> ? V : never }
+
+/**
+ * A read-only cell computed from other cells and recomputed whenever one of them changes. `dispose` detaches it from its
+ * inputs; after that it keeps its last value.
+ */
+export function createDerived<D extends readonly ReadonlyCell<unknown>[], T>(
+  key: string,
+  inputs: D,
+  compute: (...values: Values<D>) => T,
+  report: ErrorSink = () => undefined,
+): { readonly cell: ReadonlyCell<T>, readonly dispose: () => void } {
+  const read = (): T => compute(...(inputs.map(input => input.get()) as unknown as Values<D>))
+  const inner = createCell<T>(key, read(), report)
+  const stops = inputs.map(input => input.subscribe(() => { inner.set(read()) }))
+  return {
+    cell: { key, get: inner.get, subscribe: inner.subscribe },
+    dispose: () => { for (const stop of stops) stop() },
+  }
+}

package/plugins/acryl-state/src/index.ts

@@ -0,0 +1,3 @@
+export { State, apply, name } from './service.ts'
+export { createCell, createDerived } from './cell.ts'
+export type { Cell, Listener, ReadonlyCell } from './cell.ts'

package/plugins/acryl-state/src/react.ts

@@ -0,0 +1,11 @@
+/**
+ * The React binding: one hook that reads a cell and re-renders when it changes. `useSyncExternalStore` is React's own
+ * contract for exactly this, so it is tear-free under concurrent rendering. Import from `acryl-state/react`.
+ */
+
+import { useSyncExternalStore } from 'react'
+import type { ReadonlyCell } from './cell.ts'
+
+export function useCell<T>(cell: ReadonlyCell<T>): T {
+  return useSyncExternalStore(listener => cell.subscribe(listener), cell.get, cell.get)
+}