golem-kit 0.1.1 → 0.2.0

package/src/backend/jobs.ts

@@ -0,0 +1,302 @@
+import { Cron } from 'croner'
+import {
+  anonymous, defineOperation, ForbiddenError, InvalidError, NotFoundError, RecordRefusedError, z,
+  type JobContext, type Operation, type Principal, type RecordStore, type Row,
+} from '../operations.ts'
+
+/** Reserved collections: the records operations refuse `_` names, so run state never leaks through them. */
+export const SCHEDULES = '_job_schedules'
+export const RUNS = '_job_runs'
+// Finished runs are kept; there is no retention limit yet.
+/** The only name job state puts on the change stream; readers re-list through `jobs.runs`. */
+export const JOBS_CHANGE = '_jobs'
+
+/** An app-owned job: which registered operation it runs. Callers pick the job and its input, never the operation or who it acts for. */
+export type JobDefinition = {
+  name: string
+  description: string
+  /** A registered operation; each run goes through `invoke` and `authorize` like any other call. */
+  operation: string
+  /** Signed-out guests may start and schedule it; its runs act as `anonymous`. Apps without accounts are always anonymous. */
+  anonymous?: boolean
+  /** A scheduled time that passed while the server was down: `skip` (default) waits for the next one, `once` runs one catch-up at start. */
+  missed?: 'skip' | 'once'
+}
+
+type Deps = {
+  store: RecordStore
+  definitions(): JobDefinition[]
+  hasAccounts: boolean
+  resolveAccount(id: string): Promise<Principal>
+  invoke(name: string, input: unknown, principal: Principal, job: JobContext): Promise<unknown>
+  emit(): void
+}
+
+const maxDelay = 2 ** 31 - 1
+const now = () => new Date().toISOString()
+
+/**
+ * Durable server-side runs of app operations, started by hand or by an interval/cron schedule.
+ * A run outlives the request that started it; one found still running at start was cut off by a
+ * stop, so it becomes `interrupted` and waits for someone to retry or dismiss it — never replayed.
+ */
+export function createJobs(deps: Deps) {
+  const { store } = deps
+  const definition = (name: string) => deps.definitions().find((one) => one.name === name)
+  const active = new Map<string, AbortController>()
+  const timers = new Map<string, NodeJS.Timeout>()
+  let closed = false
+  // Claims (a slot firing, a retry, an unschedule) read and write run state in one step, one at a time,
+  // so two callers never both see a run as unclaimed. Operations themselves run outside this queue.
+  let queue: Promise<unknown> = Promise.resolve()
+  const serial = <T>(step: () => Promise<T>): Promise<T> => {
+    const result = queue.then(step)
+    queue = result.catch(() => {})
+    return result
+  }
+
+  async function all(collection: string, filter?: Record<string, string | null>): Promise<Row[]> {
+    const rows: Row[] = []
+    let cursor: string | null = null
+    do {
+      const page: Awaited<ReturnType<RecordStore['list']>> = await store.list(collection, { filter, cursor, limit: 500 })
+      rows.push(...page.rows)
+      cursor = page.nextCursor
+    } while (cursor)
+    return rows
+  }
+  const write = async <T>(result: Promise<T>) => { const value = await result; deps.emit(); return value }
+
+  function nextAfter(schedule: Record<string, unknown>, from: Date): string {
+    if (typeof schedule.every === 'number') return new Date(from.getTime() + (schedule.every as number) * 1000).toISOString()
+    const next = new Cron(String(schedule.cron), { timezone: String(schedule.timezone), paused: true }).nextRun(from)
+    if (!next) throw new InvalidError('This cron expression never runs again')
+    return next.toISOString()
+  }
+
+  function job(name: string): JobDefinition {
+    const found = definition(name)
+    if (!found) throw new NotFoundError(`Unknown job: ${name}`)
+    return found
+  }
+
+  /** The job as it was when the run or schedule was made: a removed job, or one now pointing at another operation, never runs. */
+  function unchanged(row: Row): JobDefinition {
+    const found = job(String(row.job))
+    if (found.operation !== row.operation) throw new RecordRefusedError(`Job ${found.name} now runs ${found.operation}, not ${String(row.operation)}; schedule it again`)
+    return found
+  }
+
+  /** Runs are owned by the account that started them; nobody reads or acts on someone else's. */
+  function owned(row: Row | null, principal: Principal): Row {
+    const owner = principal.kind === 'user' ? principal.id : null
+    if (!row || (row.accountId ?? null) !== owner) throw new NotFoundError('No such job run or schedule')
+    return row
+  }
+
+  function actor(definition: JobDefinition, principal: Principal): string | null {
+    if (principal.kind === 'user') {
+      if (!deps.hasAccounts) throw new ForbiddenError('Jobs that act for a person need local accounts')
+      return principal.id
+    }
+    if (deps.hasAccounts && !definition.anonymous) throw new ForbiddenError(`Sign in to run ${definition.name}`)
+    return null
+  }
+
+  async function execute(run: Row): Promise<void> {
+    const controller = new AbortController()
+    active.set(run.id, controller)
+    const context: JobContext = {
+      runId: run.id,
+      key: String(run.key),
+      signal: controller.signal,
+      progress: async (progress) => { await write(store.update(RUNS, run.id, { progress })) },
+    }
+    let patch: Record<string, unknown>
+    try {
+      const definition = unchanged(run)
+      // Current roles and groups on every run: a removed account or a lost role stops its jobs.
+      const principal = run.accountId ? await deps.resolveAccount(String(run.accountId)) : anonymous
+      const result = await deps.invoke(definition.operation, run.input, principal, context)
+      patch = { status: 'succeeded', result: result ?? null }
+    } catch (error) {
+      const failure = error instanceof Error ? `${error.name}: ${error.message}` : String(error)
+      patch = { status: controller.signal.aborted ? 'cancelled' : 'failed', error: failure }
+    } finally {
+      active.delete(run.id)
+    }
+    if (!closed) await write(store.update(RUNS, run.id, { ...patch, finishedAt: now() })).catch((error) => console.error(error))
+  }
+
+  async function begin(fields: { job: string; operation: string; input: unknown; accountId: string | null; scheduleId: string | null; key?: string; retryOf?: string }): Promise<Row> {
+    const id = crypto.randomUUID()
+    const run = await write(store.create(RUNS, { id, ...fields, key: fields.key ?? id, status: 'running', progress: null, startedAt: now(), cancelRequested: false }))
+    void execute(run)
+    return run
+  }
+
+  const tick = (scheduleId: string) => serial(async () => {
+    timers.delete(scheduleId)
+    if (closed) return
+    const schedule = await store.get(SCHEDULES, scheduleId)
+    if (!schedule) return
+    const slot = String(schedule.nextRunAt)
+    if (Date.parse(slot) > Date.now()) return arm(schedule)
+    await fire(schedule, slot, new Date())
+  })
+
+  /**
+   * One scheduled slot. Overlap is skipped: while a run of this schedule is still running (a
+   * cancelled one included, until its operation returns), or was interrupted and nobody has retried
+   * or dismissed it, the slot is recorded as skipped instead. So is a slot whose job was removed or changed.
+   */
+  async function fire(schedule: Row, slot: string, from: Date): Promise<void> {
+    const pending = (await all(RUNS, { scheduleId: schedule.id })).some((run) => run.status === 'running' || (run.status === 'interrupted' && !run.resolution))
+    let problem: string | null = null
+    try { unchanged(schedule) } catch (error) { problem = (error as Error).message }
+    const skip = pending || problem !== null
+    const next = await store.update(SCHEDULES, schedule.id, { nextRunAt: nextAfter(schedule, from), error: problem, ...(skip ? { lastSkippedAt: slot } : { lastRunAt: slot }) })
+    deps.emit()
+    if (!skip) await begin({ job: String(schedule.job), operation: String(schedule.operation), input: schedule.input, accountId: (schedule.accountId as string | null) ?? null, scheduleId: schedule.id, key: `${schedule.id}-${Date.parse(slot)}` })
+    arm(next)
+  }
+
+  function arm(schedule: Row): void {
+    clearTimeout(timers.get(schedule.id))
+    if (closed) return
+    const delay = Math.min(Math.max(Date.parse(String(schedule.nextRunAt)) - Date.now(), 0), maxDelay)
+    const timer = setTimeout(() => void tick(schedule.id).catch((error) => console.error(error)), delay)
+    timers.set(schedule.id, timer.unref())
+  }
+
+  async function start(): Promise<void> {
+    for (const run of await all(RUNS, { status: 'running' })) {
+      await store.update(RUNS, run.id, { status: 'interrupted', finishedAt: now(), error: 'The server stopped while this run was in progress. Its effects may be partial; retry or dismiss it.' })
+    }
+    for (const schedule of await all(SCHEDULES)) {
+      const slot = String(schedule.nextRunAt)
+      if (Date.parse(slot) > Date.now()) { arm(schedule); continue }
+      if (definition(String(schedule.job))?.missed === 'once') { await serial(() => fire(schedule, slot, new Date())); continue }
+      arm(await store.update(SCHEDULES, schedule.id, { nextRunAt: nextAfter(schedule, new Date()), lastMissedAt: slot }))
+    }
+    deps.emit()
+  }
+
+  const ready = start().catch((error) => { console.error('Jobs failed to start', error) })
+
+  const runRecord = (input: { id: string }) => ({ collection: RUNS, id: input.id })
+  const scheduleRecord = (input: { id: string }) => ({ collection: SCHEDULES, id: input.id })
+  const row = z.looseObject({ id: z.string(), version: z.number() })
+  const id = z.string().min(1)
+  const input = z.unknown().optional()
+
+  // Management goes through `invoke`, so the app's `authorize` sees each call (and the run or schedule as `record`).
+  const operations: Operation[] = [
+    defineOperation({
+      name: 'jobs.list', description: 'List the app jobs and your schedules.',
+      input: z.object({}), output: z.object({ jobs: z.array(z.object({ name: z.string(), description: z.string() })), schedules: z.array(row) }),
+      async run(_, { principal, permits }) {
+        await ready
+        const owner = principal.kind === 'user' ? principal.id : null
+        const mine = (await all(SCHEDULES, { accountId: owner }))
+        const visible = await Promise.all(mine.map(permits))
+        return { jobs: deps.definitions().map(({ name, description }) => ({ name, description })), schedules: mine.filter((_, index) => visible[index]) }
+      },
+    }),
+    defineOperation({
+      name: 'jobs.start', description: 'Start one run of a job now. It keeps running if the browser goes away.',
+      input: z.object({ job: z.string(), input }), output: row,
+      async run(request, { principal }) {
+        await ready
+        const definition = job(request.job)
+        return begin({ job: definition.name, operation: definition.operation, input: request.input ?? {}, accountId: actor(definition, principal), scheduleId: null })
+      },
+    }),
+    defineOperation({
+      name: 'jobs.schedule', description: 'Run a job every N seconds, or on a cron expression in an explicit IANA timezone.',
+      input: z.union([
+        z.object({ job: z.string(), input, every: z.number().int().min(10) }),
+        z.object({ job: z.string(), input, cron: z.string().max(120), timezone: z.string().max(64) }),
+      ]),
+      output: row,
+      async run(request, { principal }) {
+        await ready
+        const definition = job(request.job)
+        const timing = 'every' in request ? { every: request.every } : { cron: request.cron, timezone: request.timezone }
+        let nextRunAt: string
+        try { nextRunAt = nextAfter(timing, new Date()) } catch (error) { throw new InvalidError(`Invalid schedule: ${(error as Error).message}`) }
+        const schedule = await write(store.create(SCHEDULES, { job: definition.name, operation: definition.operation, input: request.input ?? {}, accountId: actor(definition, principal), ...timing, nextRunAt }))
+        arm(schedule)
+        return schedule
+      },
+    }),
+    defineOperation({
+      name: 'jobs.unschedule', description: 'Stop a schedule. Runs it already started are unaffected.',
+      input: z.object({ id }), output: z.null(), record: scheduleRecord,
+      run: (request, { principal }) => serial(async () => {
+        owned(await store.get(SCHEDULES, request.id), principal)
+        clearTimeout(timers.get(request.id))
+        timers.delete(request.id)
+        await write(store.remove(SCHEDULES, request.id))
+        return null
+      }),
+    }),
+    defineOperation({
+      name: 'jobs.runs', description: 'Your recent job runs, newest first, with status, progress, result and error.',
+      input: z.object({ job: z.string().optional(), scheduleId: z.string().optional(), limit: z.number().int().min(1).max(200).optional() }),
+      output: z.array(row),
+      async run(request, { principal, permits }) {
+        await ready
+        const filter: Record<string, string | null> = { accountId: principal.kind === 'user' ? principal.id : null }
+        if (request.job) filter.job = request.job
+        if (request.scheduleId) filter.scheduleId = request.scheduleId
+        const page = await store.list(RUNS, { filter, sort: { field: 'startedAt', direction: 'desc' }, limit: request.limit ?? 50 })
+        const visible = await Promise.all(page.rows.map(permits))
+        return page.rows.filter((_, index) => visible[index])
+      },
+    }),
+    defineOperation({
+      name: 'jobs.cancel', description: 'Ask a running job to stop. The operation stops at its next check; work it already did stays done.',
+      input: z.object({ id }), output: row, record: runRecord,
+      async run(request, { principal }) {
+        const run = owned(await store.get(RUNS, request.id), principal)
+        const controller = active.get(run.id)
+        if (run.status !== 'running' || !controller) throw new RecordRefusedError('Only a running job can be cancelled')
+        const updated = await write(store.update(RUNS, run.id, { cancelRequested: true }))
+        controller.abort(new Error('Cancelled'))
+        return updated
+      },
+    }),
+    defineOperation({
+      name: 'jobs.resolve', description: 'Settle an interrupted run: retry starts a new run with the same input and idempotency key; dismiss leaves it as is.',
+      input: z.object({ id, action: z.enum(['retry', 'dismiss']) }), output: row, record: runRecord,
+      run: (request, { principal }) => serial(async () => {
+        const run = owned(await store.get(RUNS, request.id), principal)
+        if (run.status !== 'interrupted' || run.resolution) throw new RecordRefusedError('Only an unsettled interrupted run can be retried or dismissed')
+        if (request.action === 'dismiss') return write(store.update(RUNS, run.id, { resolution: 'dismissed' }))
+        // Re-checks who may start the job now: the retry acts as the same account with its current roles.
+        actor(unchanged(run), principal)
+        // The retry exists before the old run is marked settled: a stop in between leaves both visible, never neither.
+        const retry = await begin({ job: String(run.job), operation: String(run.operation), input: run.input, accountId: (run.accountId as string | null) ?? null, scheduleId: (run.scheduleId as string | null) ?? null, key: String(run.key), retryOf: run.id })
+        await write(store.update(RUNS, run.id, { resolution: 'retried', retryId: retry.id }))
+        return retry
+      }),
+    }),
+  ]
+
+  return {
+    operations,
+    /** Resolves once interrupted runs are marked and schedules armed. */
+    ready,
+    /**
+     * Stops the timers and aborts every running operation's signal. Nothing more is recorded: those
+     * runs stay `running` and become `interrupted` at the next start, whatever their operations did meanwhile.
+     */
+    close() {
+      closed = true
+      for (const timer of timers.values()) clearTimeout(timer)
+      timers.clear()
+      for (const controller of active.values()) controller.abort(new Error('The server is stopping'))
+    },
+  }
+}

package/src/backend/jsonl.ts

@@ -0,0 +1,87 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, open, readFile, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { NotFoundError, RecordRefusedError, validCollection, validId, type RecordStore, type Row } from '../operations.ts'
+import { json, nextVersion, page } from './rules.ts'
+
+type Entry = { put: Row } | { remove: string }
+
+/**
+ * One append-only JSONL log per collection, replayed into memory on first use and fsynced per write.
+ * Single-process only and one write at a time; use the SQLite store for anything busier.
+ */
+export async function jsonlStore(directory: string): Promise<RecordStore & { native: string }> {
+  await mkdir(directory, { recursive: true })
+  const collections = new Map<string, Map<string, Row>>()
+  let queue: Promise<unknown> = Promise.resolve()
+  const serial = <T>(work: () => Promise<T>): Promise<T> => {
+    const run = queue.then(work)
+    queue = run.catch(() => {})
+    return run
+  }
+  const file = (collection: string) => join(directory, `${validCollection(collection)}.jsonl`)
+
+  async function load(collection: string): Promise<Map<string, Row>> {
+    const loaded = collections.get(collection)
+    if (loaded) return loaded
+    const rows = new Map<string, Row>()
+    let text = ''
+    try { text = await readFile(file(collection), 'utf8') } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+    // A crash can leave one torn line at the end; everything before the last newline was acknowledged.
+    const complete = text.slice(0, text.lastIndexOf('\n') + 1)
+    const lines = complete.split('\n').filter(Boolean)
+    for (const line of lines) {
+      const entry = JSON.parse(line) as Entry
+      if ('put' in entry) rows.set(entry.put.id, entry.put)
+      else rows.delete(entry.remove)
+    }
+    if (complete.length !== text.length || lines.length > rows.size * 2 + 100) {
+      const temporary = `${file(collection)}.${process.pid}.tmp`
+      await writeFile(temporary, [...rows.values()].map((row) => `${JSON.stringify({ put: row })}\n`).join(''), { flush: true })
+      await rename(temporary, file(collection))
+    }
+    collections.set(collection, rows)
+    return rows
+  }
+
+  async function append(collection: string, entry: Entry): Promise<void> {
+    const handle = await open(file(collection), 'a')
+    try {
+      await handle.appendFile(`${JSON.stringify(entry)}\n`)
+      await handle.datasync()
+    } finally {
+      await handle.close()
+    }
+  }
+
+  return {
+    native: directory,
+    async list(collection, query) { return structuredClone(page([...(await serial(() => load(collection))).values()], query)) },
+    async get(collection, id) { return structuredClone((await serial(() => load(collection))).get(validId(id)) ?? null) },
+    create: (collection, data) => serial(async () => {
+      const rows = await load(collection)
+      const id = data.id === undefined ? randomUUID() : validId(String(data.id))
+      if (rows.has(id)) throw new RecordRefusedError(`A record with id ${id} already exists`, [{ field: 'id', message: 'This id is already taken.' }])
+      const now = new Date().toISOString()
+      const row: Row = { ...json(data), id, version: 1, createdAt: now, updatedAt: now }
+      await append(collection, { put: row })
+      rows.set(id, row)
+      return structuredClone(row)
+    }),
+    update: (collection, id, patch, options) => serial(async () => {
+      const rows = await load(collection)
+      const current = rows.get(validId(id))
+      const row = nextVersion(collection, id, current, patch, options)
+      await append(collection, { put: row })
+      rows.set(id, row)
+      return structuredClone(row)
+    }),
+    remove: (collection, id) => serial(async () => {
+      const rows = await load(collection)
+      if (!rows.has(validId(id))) throw new NotFoundError(`No ${collection} record ${id}`)
+      await append(collection, { remove: id })
+      rows.delete(id)
+    }),
+    close: () => serial(async () => { collections.clear() }),
+  }
+}

package/src/backend/knowledge.ts

@@ -0,0 +1,264 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { link, lstat, mkdir, open, readdir, realpath, rename, unlink, writeFile } from 'node:fs/promises'
+import { dirname, join, relative, sep } from 'node:path'
+import {
+  defineOperation, ForbiddenError, InvalidError, NotFoundError, validCollection, VersionConflictError, z,
+  type Operation, type RecordStore, type Row,
+} from '../operations.ts'
+
+/** Internal collection holding one revision row per file: the numeric version Editor saves against and the last sha256 seen. */
+export const KNOWLEDGE_COLLECTION = '_knowledge'
+
+/** Knowledge roots an app's server module opts into: root name → directory relative to the app root. */
+export type KnowledgeRoots = Record<string, string>
+
+/** One markdown file as operations return it. `id` is the path, so it plugs into golem-ui's Records contract. */
+export type KnowledgeFile = Row & { root: string; path: string; body: string; sha256: string; type: string | null; title: string }
+
+const maxBytes = 2_000_000
+
+// One queue per absolute file path, shared across server-module reloads.
+// In-process only: a second server process on the same app is not covered.
+const locks = new Map<string, Promise<unknown>>()
+function serial<T>(key: string, work: () => Promise<T>): Promise<T> {
+  const next = (locks.get(key) ?? Promise.resolve()).then(work, work)
+  const settled = next.catch(() => {})
+  locks.set(key, settled)
+  void settled.then(() => { if (locks.get(key) === settled) locks.delete(key) })
+  return next
+}
+const segment = /^[^/\\\0.][^/\\\0]{0,127}$/
+
+/** A relative `.md` path inside a root: no `..`, no hidden segments, no backslashes. */
+export function validPath(value: string): string {
+  const parts = typeof value === 'string' ? value.split('/') : []
+  if (!parts.length || value.length > 512 || !value.endsWith('.md') || !parts.every((part) => segment.test(part))) {
+    throw new InvalidError(`Invalid knowledge path: ${JSON.stringify(value)}`)
+  }
+  return value
+}
+
+/** What `authorize` sees as `record` for every knowledge operation, whether or not the file exists yet. */
+export const knowledgeEntry = (root: string, path: string): Row => ({ id: `${root}/${path}`, root, path, version: 0, createdAt: '', updatedAt: '' })
+
+/**
+ * Markdown files under trusted roots, versioned for Editor. Golem's own writes are serialized per
+ * file and compare the disk bytes against the version they were given right before the rename;
+ * an edit made on disk since the last read shows up as a new version. Editors that do not go through
+ * Golem are not locked out: one that writes in the instant between that check and the rename is overwritten.
+ */
+export function knowledgeOperations(appRoot: string, roots: KnowledgeRoots): Operation[] {
+  if (!roots || typeof roots !== 'object' || Array.isArray(roots)) throw new Error('knowledge must map root names to directories')
+  for (const [name, directory] of Object.entries(roots)) {
+    validCollection(name)
+    if (typeof directory !== 'string' || !directory || directory.startsWith('/') || directory.split(/[/\\]/).includes('..')) {
+      throw new Error(`knowledge root ${name} must be a directory inside the app`)
+    }
+  }
+  // Policy: no symlink anywhere between the app root and a file, so a path is also the file's one identity.
+  async function base(root: string): Promise<string> {
+    if (!Object.hasOwn(roots, root)) throw new NotFoundError(`No knowledge root ${root}`)
+    const app = await realpath(appRoot)
+    const top = join(app, roots[root])
+    if (!(await unlinked(app, top))) throw new NotFoundError(`Knowledge root ${root} has no directory`)
+    return top
+  }
+
+  /** Absolute path of a file under the root; every folder on the way is a real directory, and the file is opened without following links. */
+  async function locate(root: string, path: string): Promise<string> {
+    const top = await base(root)
+    const file = join(top, validPath(path))
+    await unlinked(top, dirname(file))
+    return file
+  }
+
+  async function readDisk(file: string): Promise<Buffer | null> {
+    let handle
+    try {
+      handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW)
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') return null
+      if (code === 'ELOOP') throw new ForbiddenError('Knowledge files may not be symlinks')
+      throw error
+    }
+    try {
+      const stat = await handle.stat()
+      // A second hard link would be a second name for the same bytes, possibly outside the root.
+      if (!stat.isFile() || stat.nlink > 1) throw new ForbiddenError('Not a knowledge file')
+      const bytes = await handle.readFile()
+      if (bytes.byteLength > maxBytes) throw new InvalidError('Knowledge file is too large')
+      return bytes
+    } finally {
+      await handle.close()
+    }
+  }
+
+  /** The revision row for these bytes: a sha the store has not seen yet bumps the version. */
+  async function revision(records: RecordStore, root: string, path: string, bytes: Buffer): Promise<Row> {
+    const id = createHash('sha256').update(`${root}\0${path}`).digest('hex').slice(0, 40)
+    const sha256 = hash(bytes)
+    const row = await records.get(KNOWLEDGE_COLLECTION, id)
+    if (!row) return records.create(KNOWLEDGE_COLLECTION, { id, root, path, sha256 })
+    return row.sha256 === sha256 ? row : records.update(KNOWLEDGE_COLLECTION, id, { sha256 })
+  }
+
+  async function read(records: RecordStore, root: string, path: string): Promise<KnowledgeFile> {
+    const file = await locate(root, path)
+    return serial(file, async () => {
+      const bytes = await readDisk(file)
+      if (!bytes) throw new NotFoundError(`No knowledge file ${root}/${path}`)
+      return toFile(root, path, bytes, await revision(records, root, path, bytes))
+    })
+  }
+
+  async function write(records: RecordStore, root: string, path: string, body: string, expectedVersion: number): Promise<KnowledgeFile> {
+    const file = await locate(root, path)
+    return serial(file, async () => {
+      const before = await readDisk(file)
+      const current = before && await revision(records, root, path, before)
+      const conflict = async () => new VersionConflictError(`${root}/${path} changed since it was read`, before && current ? toFile(root, path, before, current) : null)
+      if (current ? current.version !== expectedVersion : expectedVersion !== 0) throw await conflict()
+      const bytes = Buffer.from(body, 'utf8')
+      if (bytes.byteLength > maxBytes) throw new InvalidError('Knowledge file is too large')
+      if (!before) await mkdirInside(await base(root), dirname(file))
+      const temporary = join(dirname(file), `.${randomUUID()}.golem-write`)
+      await writeFile(temporary, bytes, { flush: true, flag: 'wx' })
+      try {
+        if (!before) {
+          // link() refuses an existing name: a file created meanwhile is a conflict, not overwritten.
+          await link(temporary, file).catch(async (error) => { throw error.code === 'EEXIST' ? await conflict() : error })
+        } else {
+          const latest = await readDisk(file)
+          if (!latest || hash(latest) !== hash(before)) throw new VersionConflictError(`${root}/${path} changed on disk while saving`, latest ? toFile(root, path, latest, await revision(records, root, path, latest)) : null)
+          await rename(temporary, file)
+        }
+      } finally {
+        await unlink(temporary).catch(() => {})
+      }
+      return toFile(root, path, bytes, await revision(records, root, path, bytes))
+    })
+  }
+
+  async function* walk(top: string, folder: string): AsyncGenerator<string> {
+    const entries = await readdir(join(top, folder), { withFileTypes: true }).catch(() => [])
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.name.startsWith('.')) continue
+      const path = folder ? `${folder}/${entry.name}` : entry.name
+      // Symlinked entries are skipped, so a link never pulls outside content into a listing.
+      if (entry.isDirectory()) yield* walk(top, path)
+      else if (entry.isFile() && entry.name.endsWith('.md')) yield path
+    }
+  }
+
+  const root = z.string().min(1)
+  const path = z.string().transform((value, context) => {
+    try { return validPath(value) } catch (error) { context.addIssue({ code: 'custom', message: (error as Error).message }); return z.NEVER }
+  })
+  const entry = (input: { root: string; path: string }) => ({ row: knowledgeEntry(input.root, input.path) })
+  const fileRow = z.looseObject({ id: z.string(), root: z.string(), path: z.string(), version: z.number(), body: z.string() })
+  const listed = z.looseObject({ id: z.string(), root: z.string(), path: z.string(), version: z.number(), title: z.string(), type: z.string().nullable() })
+
+  // Folder paths are validated like file paths, minus the extension.
+  const folder = z.string().refine((value) => value === '' || value.split('/').every((part) => segment.test(part)), 'must be a relative folder')
+  async function files(input: { root: string; folder?: string }, permits: (row: Row) => Promise<boolean>) {
+    const top = await base(input.root)
+    if (input.folder && !(await unlinked(top, join(top, input.folder)))) return []
+    const found: string[] = []
+    for await (const one of walk(top, input.folder ?? '')) {
+      if (await permits(knowledgeEntry(input.root, one))) found.push(one)
+    }
+    return found
+  }
+
+  return [
+    defineOperation({
+      name: 'knowledge.list',
+      description: 'List markdown files in a knowledge root (optionally one folder), with their title, OKF type and version. Start here to find sources.',
+      input: z.object({ root, folder: folder.optional() }),
+      output: z.object({ rows: z.array(listed), nextCursor: z.null() }),
+      async run(input, { records, permits }) {
+        const rows = []
+        for (const one of await files(input, permits)) {
+          const file = await read(records, input.root, one).catch(() => null)
+          if (file) rows.push(summary(file))
+        }
+        return { rows, nextCursor: null }
+      },
+    }),
+    defineOperation({
+      name: 'knowledge.search',
+      description: 'Find lines containing some text across a knowledge root. Returns path, 1-based line number and that line, so an answer can cite its source.',
+      input: z.object({ root, text: z.string().min(2).max(200), limit: z.number().int().min(1).max(100).optional() }),
+      output: z.array(z.object({ path: z.string(), line: z.number(), text: z.string() })),
+      async run(input, { records, permits }) {
+        const needle = input.text.toLowerCase()
+        const hits: Array<{ path: string; line: number; text: string }> = []
+        for (const one of await files(input, permits)) {
+          const file = await read(records, input.root, one).catch(() => null)
+          file?.body.split('\n').forEach((text, index) => { if (text.toLowerCase().includes(needle)) hits.push({ path: one, line: index + 1, text: text.slice(0, 400) }) })
+          if (hits.length >= (input.limit ?? 30)) break
+        }
+        return hits.slice(0, input.limit ?? 30)
+      },
+    }),
+    defineOperation({
+      name: 'knowledge.read',
+      description: 'Read one markdown file: its whole text (frontmatter included) as `body`, and the `version` a write must send back.',
+      input: z.object({ root, path }), output: fileRow, record: entry,
+      run: (input, { records }) => read(records, input.root, input.path),
+    }),
+    defineOperation({
+      name: 'knowledge.write',
+      description: 'Replace one markdown file with `body`. Send the `version` you read (0 to create a new file); a file changed since then is refused with the current text.',
+      input: z.object({ root, path, body: z.string(), expectedVersion: z.number().int().min(0) }), output: fileRow, record: entry,
+      run: (input, { records }) => write(records, input.root, input.path, input.body, input.expectedVersion),
+    }),
+  ]
+}
+
+/** True when every step from `top` down to `target` exists as a real directory; a symlink on the way is refused. */
+async function unlinked(top: string, target: string): Promise<boolean> {
+  let at = top
+  for (const part of relative(top, target).split(sep).filter(Boolean)) {
+    at = join(at, part)
+    const stat = await lstat(at).catch(() => null)
+    if (!stat) return false
+    if (!stat.isDirectory()) throw new ForbiddenError('Path leaves the knowledge root')
+  }
+  return true
+}
+
+async function mkdirInside(top: string, directory: string): Promise<void> {
+  const parts = relative(top, directory).split(sep).filter(Boolean)
+  let at = top
+  for (const part of parts) {
+    at = join(at, part)
+    const stat = await lstat(at).catch(() => null)
+    if (!stat) await mkdir(at).catch((error) => { if (error.code !== 'EEXIST') throw error })
+    else if (!stat.isDirectory()) throw new ForbiddenError('Path leaves the knowledge root')
+  }
+}
+
+const hash = (bytes: Uint8Array) => createHash('sha256').update(bytes).digest('hex')
+
+function toFile(root: string, path: string, bytes: Buffer, revision: Row): KnowledgeFile {
+  const body = bytes.toString('utf8')
+  const meta = frontmatter(body)
+  const title = meta.title || /^#\s+(.+)$/m.exec(body)?.[1]?.trim() || path.split('/').pop()!.replace(/\.md$/, '')
+  return { id: path, root, path, body, sha256: revision.sha256 as string, type: meta.type || null, title, version: revision.version, createdAt: revision.createdAt, updatedAt: revision.updatedAt }
+}
+
+const summary = ({ body: _body, ...rest }: KnowledgeFile) => rest
+
+/** Top-level scalar keys of a YAML frontmatter block; enough for OKF's `type`, `title` and `description`. */
+function frontmatter(text: string): Record<string, string> {
+  const block = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(text)?.[1]
+  const out: Record<string, string> = {}
+  for (const line of block?.split(/\r?\n/) ?? []) {
+    const match = /^([A-Za-z_][\w-]*):\s*(.*?)\s*$/.exec(line)
+    if (match && match[2]) out[match[1]] = match[2].replace(/^(['"])(.*)\1$/, '$2')
+  }
+  return out
+}