dimcode-darwin-x64 0.1.0-alpha.14 → 0.1.0-alpha.16

package/plugins/scheduler/index.ts

@@ -0,0 +1,164 @@
+import { definePlugin } from '@arcships/rutis'
+import { z } from 'zod'
+import type { JsonObject, ManagementMethods, PartRegistry, PluginFiles, SessionPermissions, Sessions, Settings } from '../../../npm/plugin.js'
+import { ScheduleError, type Job } from './data.ts'
+import { Scheduler } from './engine.ts'
+import { Jobs } from './jobs.ts'
+import { bounded, management, unloadingBeforeCall, type ScheduleJobs } from './requests.ts'
+import session from './session.ts'
+import { settings } from './settings.ts'
+import { RunStore, type Run } from './store.ts'
+import { windowAfter } from './windows.ts'
+
+/// The plugin's factory configuration: the tool description and the
+/// report's guidance line, each one whole text. `report_guidance` is one
+/// line: the entry names the report's last line as guidance, not part of
+/// the scheduler's account, so a value with a line break is refused.
+const guidance = z.string().min(1).refine(value => !/[\r\n]/.test(value), {
+  message: 'report_guidance must be one line: the entry names the report\'s last line as guidance',
+})
+const options = z.strictObject({ description: z.string().min(1).optional(), report_guidance: guidance.optional() })
+
+function jobPreview(job: Job) {
+  return { ...job, name: bounded(job.name, 256), prompt: bounded(job.prompt, 4 * 1024),
+    prompt_truncated: Buffer.byteLength(job.prompt) > 4 * 1024 }
+}
+
+function runPreview(run: Run) { return { ...run, detail: bounded(run.detail, 512) } }
+
+export default definePlugin({
+  name: 'Scheduler',
+  // A plain JSON Schema: zod's result also carries `~standard`, which
+  // rutis refuses as a Standard Schema.
+  config: JSON.parse(JSON.stringify(z.toJSONSchema(options))),
+  inject: ['sessions', 'sessionPermissions', 'settings', 'pluginFiles', 'managementMethods', 'partRegistry'],
+  provides: { scheduleJobs: { call: 'async' } },
+  async apply(ctx, config: z.infer<typeof options>) {
+    config = options.parse(config)
+    await ctx.use<Settings>('settings').register(settings)
+    const jobs = new Jobs(ctx.use<Settings>('settings'), ctx.use<SessionPermissions>('sessionPermissions'))
+    const scope = await ctx.use<PluginFiles>('pluginFiles').open()
+    const scheduler = new Scheduler(jobs, ctx.use<Sessions>('sessions'), new RunStore(scope), config.report_guidance)
+    ctx.effect(() => scheduler.close())
+
+    async function list() {
+      const { document } = await jobs.read()
+      const runs = await scheduler.store.read()
+      return { jobs: document.jobs.map(job => {
+        const ownRuns = runs.filter(run => run.job_id === job.id).sort((a, b) => b.created_at.localeCompare(a.created_at) || b.run_id.localeCompare(a.run_id))
+        const windows = ownRuns.filter(run => run.window !== 'manual').map(run => run.window).sort()
+        const after = windows.length ? Date.parse(windows.at(-1)!)
+          : 'at' in job.schedule ? Number.NEGATIVE_INFINITY : Date.parse(job.enabled_at!) - 1
+        let next_window: string | null = null, issue: string | undefined
+        try {
+          const next = job.enabled ? windowAfter(job, after) : undefined
+          if (next !== undefined) next_window = new Date(next).toISOString()
+        }
+        catch (error) { issue = error instanceof Error ? error.message : String(error) }
+        return { ...job, next_window,
+          ...(issue ? { schedule_error: issue } : {}), last_run: ownRuns[0] ?? null }
+      }) }
+    }
+    const history = async (jobId: string, limit: number) => ({ runs: (await scheduler.store.read()).filter(run => run.job_id === jobId)
+      .sort((a, b) => b.created_at.localeCompare(a.created_at) || b.run_id.localeCompare(a.run_id)).slice(0, limit) })
+    async function remove(jobId: string) {
+      const result = await jobs.delete(jobId)
+      await scheduler.prune()
+      return result
+    }
+
+    const owner: ScheduleJobs = {
+      async call(request) {
+        try {
+          return await scheduler.track(async () => {
+            let records: JsonObject, visible: JsonObject
+            if (request.action === 'list') {
+              const listed = await list()
+              records = listed
+              visible = { jobs: listed.jobs.map(({ prompt, ...job }) => ({ ...job,
+                name: bounded(job.name, 256), last_run: job.last_run ? runPreview(job.last_run) : null,
+                ...(job.schedule_error ? { schedule_error: bounded(job.schedule_error, 512) } : {}),
+              })) }
+            } else if (request.action === 'get') {
+              const job = await jobs.get(request.job_id)
+              records = { job }; visible = { job: jobPreview(job) }
+            }
+            else if (request.action === 'create' || request.action === 'update') {
+              const saved = await jobs.save({ ...request.job, ...(request.action === 'update' ? { id: request.job_id } : {}) }, request.caller)
+              records = saved; visible = { ...saved, job: jobPreview(saved.job) }
+            } else if (request.action === 'set_enabled') {
+              const job = await jobs.setEnabled(request.job_id, request.enabled)
+              records = { job }; visible = { job: jobPreview(job) }
+            } else if (request.action === 'delete') visible = records = await remove(request.job_id)
+            else if (request.action === 'run_now') {
+              const run = await scheduler.accept(request.job_id)
+              records = run; visible = runPreview(run)
+            } else {
+              const result = await history(request.job_id, request.limit)
+              records = result; visible = { runs: result.runs.map(runPreview) }
+            }
+            return { content: JSON.stringify(visible), records }
+          })
+        } catch (error) {
+          if (error instanceof ScheduleError && error.code === 'service_reloading') {
+            return { code: 'service_unavailable', message: unloadingBeforeCall }
+          }
+          if (error instanceof ScheduleError) return { code: error.code, message: bounded(error.message, 4 * 1024) }
+          throw error
+        }
+      },
+    }
+    try { await scheduler.restore() }
+    catch (error) { scheduler.fault = error }
+
+    await ctx.use<ManagementMethods>('managementMethods').register(
+      'schedule',
+      ['list', 'save', 'delete', 'set_enabled', 'run_now', 'history'].map(name => ({
+        name: `schedule.${name}`, mutating: name !== 'list' && name !== 'history',
+        interruption: name === 'list' || name === 'history' ? 'report' : 'drain', progress: false,
+      })),
+      async (call, cancellation) => {
+        let cancelled = false
+        void cancellation.then(() => { cancelled = true }, () => { cancelled = true })
+        await Promise.resolve()
+        if (cancelled) return { code: 'service_reloading', message: 'Scheduler call cancelled before admission' }
+        try {
+          return await scheduler.track(async () => {
+            let value: JsonObject
+            switch (call.method) {
+              case 'schedule.list': management.list.parse(call.params); value = await list(); break
+              case 'schedule.save': {
+                const input = management.save.parse(call.params)
+                value = await jobs.save(input.job, undefined, input.revision)
+                break
+              }
+              case 'schedule.delete': value = await remove(management.delete.parse(call.params).job_id); break
+              case 'schedule.set_enabled': {
+                const input = management.set_enabled.parse(call.params)
+                value = { job: await jobs.setEnabled(input.job_id, input.enabled) }
+                break
+              }
+              case 'schedule.run_now': value = await scheduler.accept(management.run_now.parse(call.params).job_id); break
+              case 'schedule.history': {
+                const input = management.history.parse(call.params)
+                value = await history(input.job_id, input.limit)
+                break
+              }
+              default: return { code: 'unknown_method', message: 'Unknown Scheduler method' }
+            }
+            return { kind: 'value' as const, value }
+          })
+        } catch (error) {
+          if (error instanceof z.ZodError) return { code: 'schedule_invalid', message: error.message }
+          if (error instanceof ScheduleError) return { code: error.code, message: error.message }
+          throw error
+        }
+      },
+    )
+    if (scheduler.fault) throw scheduler.fault
+    ctx.provide('scheduleJobs', owner)
+    await ctx.use<PartRegistry>('partRegistry').registerDefinition('session', 'SchedulerSession', session(config.description))
+    ctx.on('settings/schedule', () => scheduler.changed())
+    scheduler.startTimer()
+  },
+})

package/plugins/scheduler/jobs.ts

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto'
+import type { JsonObject, SessionPermissions, Settings } from '../../../npm/plugin.js'
+import { authority, ScheduleError, validateJob, type Caller, type Job, type JobPatch, type ScheduleSettings } from './data.ts'
+
+export class SettingsReadError extends ScheduleError {}
+
+export class Jobs {
+  readonly settings: Settings
+  readonly permissions: SessionPermissions
+  constructor(settings: Settings, permissions: SessionPermissions) {
+    this.settings = settings; this.permissions = permissions
+  }
+
+  async read() {
+    let reply
+    try { reply = await this.settings.read({ source: 'schedule', scope: 'user' }) }
+    catch (error) { throw new SettingsReadError('failed', error instanceof Error ? error.message : String(error)) }
+    if (!reply.ok) throw new SettingsReadError(reply.error.code, reply.error.message)
+    return { document: reply.value.document as unknown as ScheduleSettings, revision: reply.value.revision }
+  }
+
+  async save(patch: JobPatch, caller?: Caller, revision?: number) {
+    const snapshot = await this.read()
+    const old = snapshot.document.jobs.find(job => job.id === patch.id)
+    if (patch.id && !old) throw new ScheduleError('schedule_not_found')
+    if (revision !== undefined && revision !== (old?.revision ?? 0)) throw new ScheduleError('schedule_conflict')
+    const bound = caller ? (await this.permissions.permission({ sessionId: caller.sessionId, branchId: caller.branchId })).policy
+      : await this.permissions.permissionDefaults({})
+    const { enabled_at: oldAnchor, ...previous } = old ?? {}
+    const candidate = { ...previous, ...patch, id: old?.id ?? patch.id ?? randomUUID(),
+      cwd: patch.cwd ?? old?.cwd ?? caller?.cwd, mode: patch.mode ?? old?.mode ?? 'create',
+      max_run_minutes: patch.max_run_minutes ?? old?.max_run_minutes ?? 60,
+      enabled: patch.enabled ?? old?.enabled ?? true,
+      policy_cap: bound, created_by: caller ? { tool: { session_id: caller.sessionId, branch_id: caller.branchId } } : 'user',
+      revision: (old?.revision ?? 0) + 1,
+    } satisfies Partial<Job>
+    if (patch.mode === 'create' && patch.session_id === undefined) delete candidate.session_id
+    const { name, schedule, prompt, cwd } = candidate
+    if (name === undefined || schedule === undefined || prompt === undefined || cwd === undefined) {
+      throw new ScheduleError('schedule_invalid', 'A new job needs name, schedule, prompt and cwd')
+    }
+    const job: Job = { ...candidate, name, schedule, prompt, cwd,
+      ...(candidate.enabled ? { enabled_at: old?.enabled ? oldAnchor! : new Date().toISOString() } : {}),
+    }
+    validateJob(job)
+    const transition = { from: authority(old), to: authority(job) }
+    const jobs = old ? snapshot.document.jobs.map(value => value.id === old.id ? job : value) : [...snapshot.document.jobs, job]
+    await this.write(snapshot, jobs)
+    return { job, transition }
+  }
+
+  async get(id: string): Promise<Job> {
+    const job = (await this.read()).document.jobs.find(value => value.id === id)
+    if (!job) throw new ScheduleError('schedule_not_found')
+    return job
+  }
+
+  async setEnabled(id: string, enabled: boolean) {
+    const snapshot = await this.read()
+    const old = snapshot.document.jobs.find(job => job.id === id)
+    if (!old) throw new ScheduleError('schedule_not_found')
+    const { enabled_at, ...rest } = old
+    const job: Job = { ...rest, enabled, revision: old.revision + 1,
+      ...(enabled ? { enabled_at: old.enabled ? enabled_at! : new Date().toISOString() } : {}),
+    }
+    await this.write(snapshot, snapshot.document.jobs.map(value => value.id === id ? job : value))
+    return job
+  }
+
+  async delete(id: string) {
+    const snapshot = await this.read()
+    if (!snapshot.document.jobs.some(job => job.id === id)) throw new ScheduleError('schedule_not_found')
+    await this.write(snapshot, snapshot.document.jobs.filter(job => job.id !== id))
+    return { job_id: id }
+  }
+
+  async bind(snapshot: Job, sessionId: string): Promise<number | 'changed' | 'disabled'> {
+    const current = await this.read()
+    const job = current.document.jobs.find(value => value.id === snapshot.id)
+    if (job && !job.enabled) return 'disabled'
+    if (!job || job.revision !== snapshot.revision || job.mode !== 'reuse' || job.session_id) return 'changed'
+    const saved: Job = { ...job, session_id: sessionId, revision: job.revision + 1 }
+    const committed = await this.write(current, current.document.jobs.map(value => value.id === job.id ? saved : value))
+    return committed.jobs.find(value => value.id === job.id)!.revision
+  }
+
+  async settleWindow(snapshot: Job) {
+    const current = await this.read()
+    const job = current.document.jobs.find(value => value.id === snapshot.id)
+    if (!job || job.revision !== snapshot.revision || !job.enabled) return
+    const { enabled_at, ...rest } = job
+    const saved: Job = { ...rest, revision: job.revision + 1, enabled: false }
+    await this.write(current, current.document.jobs.map(value => value.id === job.id ? saved : value))
+  }
+
+  private async write(snapshot: { document: ScheduleSettings; revision: string }, jobs: Job[]) {
+    const reply = await this.settings.update({ source: 'schedule', scope: 'user', expectedRevision: snapshot.revision,
+      document: { ...snapshot.document, jobs } as unknown as JsonObject,
+    })
+    if (!reply.ok) throw new ScheduleError(reply.error.code === 'conflict' ? 'schedule_conflict' : reply.error.code, reply.error.message)
+    return reply.value.document as unknown as ScheduleSettings
+  }
+}

package/plugins/scheduler/node_modules/.package-lock.json

@@ -0,0 +1,48 @@
+{
+  "name": "@dimcode/scheduler",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "node_modules/@arcships/rutis": {
+      "version": "0.19.3",
+      "resolved": "https://registry.npmjs.org/@arcships/rutis/-/rutis-0.19.3.tgz",
+      "integrity": "sha512-mpeVQ2tIZFyiKibgmRtyEhFu0NW3xam/OMUWSkddXIj8a/QqyW3AiE37GKlb4ihpHtuRx1dIz9HyCYHgvnecJw==",
+      "license": "MIT",
+      "engines": {
+        "bun": ">=1.4",
+        "node": ">=22"
+      }
+    },
+    "node_modules/cron-parser": {
+      "version": "5.10.2",
+      "resolved": "https://registry.npmjs.org/cron-parser/-/cron-parser-5.10.2.tgz",
+      "integrity": "sha512-JfAYMY0LZaWQTuict8PhtF/ksSnq8xefSDmQUnnoqvkPYkU/y3UP0DTWzJKFBz0P1IXsDG8q0vY3zHkoFZOhvw==",
+      "license": "MIT",
+      "dependencies": {
+        "luxon": "^3.7.2"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/luxon": {
+      "version": "3.7.2",
+      "resolved": "https://registry.npmjs.org/luxon/-/luxon-3.7.2.tgz",
+      "integrity": "sha512-vtEhXh/gNjI9Yg1u4jX/0YVPMvxzHuGgCm6tC5kZyb08yjGWGnqAjGJvcXbqQR2P3MyMEFnRbpcdFS6PBcLqew==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/plugins/scheduler/node_modules/@arcships/rutis/README.md

@@ -0,0 +1,32 @@
+# @arcships/rutis
+
+Write [rutis](https://github.com/arcships/rutis) plugins in TypeScript or JavaScript.
+
+```ts
+import { definePlugin } from '@arcships/rutis'
+
+export default definePlugin({
+  inject: ['llm'],                              // services it uses
+  config: { type: 'object', properties: { city: { type: 'string' } } },
+  apply(ctx, config) {
+    ctx.provide('weather', new Weather(ctx.use('llm'), config.city))
+    return () => {}                             // cleanup
+  },
+})
+```
+
+What `ctx.provide` provides reaches rutis by itself, its methods the object's functions, called as `async`. `provides` is optional: `provides: { weather: { unit: 'sync' } }` marks methods `sync` and tells `rutis-host check` what the plugin provides before it runs.
+
+Test it on a real host (`rutis-host test`; `@arcships/rutis-runtime` and `@arcships/rutis-host` as dev dependencies, which `rutis-host new` adds); the plugin is the default export of its module:
+
+```ts
+import { load } from '@arcships/rutis/testing'
+
+const t = await load(plugin, { config: { city: 'Oslo' }, services: { llm: { ask: async () => 'sunny' } } })
+assert.equal(await t.service('weather').today(), 'sunny in Oslo')
+await t.unload()
+```
+
+This package has no dependencies. Events (`ctx.on`, and `ctx.emit` / `parallel` / `serial` / `waterfall` / `bail` / `filter`) are one bus across every plugin, runtime and linked node, dispatched by the host; in a test too (`host()` puts several plugins on one bus). The host installs the runtime that runs the plugin (`@arcships/rutis-runtime` for Node, `@arcships/rutis-bun` for Bun). Start a project with `npx @arcships/rutis-host new <name> --lang node` (or `--lang bun`).
+
+Guide (Chinese): [docs/guide/typescript-plugin.md](https://github.com/arcships/rutis/blob/main/docs/guide/typescript-plugin.md).

package/plugins/scheduler/node_modules/@arcships/rutis/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@arcships/rutis",
+  "version": "0.19.3",
+  "description": "Write rutis plugins in JavaScript or TypeScript: definePlugin, types and a test kit",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arcships/rutis.git",
+    "directory": "node/rutis"
+  },
+  "homepage": "https://github.com/arcships/rutis/tree/main/docs/guide#readme",
+  "keywords": ["rutis", "plugin", "rutis-plugin"],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    },
+    "./advanced": {
+      "types": "./src/advanced.d.ts",
+      "default": "./src/advanced.mjs"
+    },
+    "./testing": {
+      "types": "./src/testing.d.ts",
+      "default": "./src/testing.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=22",
+    "bun": ">=1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "@arcships/rutis-bun": "file:../../bun/rutis-bun",
+    "@arcships/rutis-runtime": "file:../rutis-runtime"
+  }
+}

package/plugins/scheduler/node_modules/@arcships/rutis/src/advanced.d.ts

@@ -0,0 +1,90 @@
+// What a plugin author rarely writes (#692): the plugin API version, the
+// marks, the value constructors and the types of the events. `definePlugin`
+// and `Context` are in `@arcships/rutis`.
+import type { Plugin } from './index.js'
+
+export type MethodKind = 'sync' | 'async'
+
+/** Where a listener is, as the logical bus describes it (#464): what a filter sees. */
+export interface ListenerDescriptor {
+  /** The event name (a prefix, for a Rust pattern listener). */
+  readonly name: string
+  /** A Rust pattern listener's prefix entry. */
+  readonly prefix: boolean
+  /** The plugin that registered it: its declared name (`PluginSpec.name`, a Cordis plugin's name), else its row's id. */
+  readonly plugin: string
+  /** Its row's id, the name the configuration gives the row (the copies a group's instances make share it); `null` for a plugin a mount loaded. */
+  readonly row: string | null
+  /** The runtime it runs in; `null` for the host's own Rust plugins. */
+  readonly runtime: string | null
+  /** The node it came from over a node link; `null` otherwise. */
+  readonly node: string | null
+  /** Its scope chain, outermost first; `[]` at the root. */
+  readonly scope: ReadonlyArray<{ readonly id: string, readonly group: string }>
+  /** A `global` listener is never filtered. */
+  readonly global: boolean
+}
+
+export interface ListenerOptions {
+  /** Run before every listener of the name registered so far. */
+  prepend?: boolean
+  /** Not subject to emitters' filters. */
+  global?: boolean
+}
+
+/** A listener: the event's arguments, then, in a `waterfall`, `next` (the rest of the chain) last. */
+export type Listener = (...args: any[]) => any
+
+/** The five ways to emit. Each reaches every listener of the name on the root's flat bus, wherever the listener runs, by the same rules as if all were in this process. Emitting `rutis/*` throws `ReservedEvent`; `internal/*` is refused. */
+export interface Emitter {
+  /** Start every listener in registration order; returns at once. A listener's failure is reported where it ran and reaches neither the emitter nor the other listeners. */
+  emit(name: string, ...args: any[]): void
+  /** Start every listener and wait for all. Failures reject with an `AggregateError` in registration order, even a single one. */
+  parallel(name: string, ...args: any[]): Promise<void>
+  /** Run the listeners one by one; resolves to the first result (not `undefined`, `null` or `false`), or `undefined`. An error stops and rejects. */
+  serial<T = any>(name: string, ...args: any[]): Promise<T | undefined>
+  /** Each listener gets `next` (no arguments) last and returns the result; not calling `next` vetoes the rest. Every argument is the event's; the end of the chain gives `undefined` (see `with` for a terminal). Returns the outermost listener's value as is (a Promise whenever a listener runs elsewhere: await it). Calling `next` twice, or after the end, gives a Promise rejected with `WaterfallNext`. */
+  waterfall: Waterfall
+  /** Synchronously, the first result as `serial`. An `async` listener, or one returning a Promise, fails it with `AsyncListener`. */
+  bail<T = any>(name: string, ...args: any[]): T | undefined
+}
+
+export interface Waterfall {
+  <T = any>(name: string, ...args: any[]): T | Promise<T>
+  /** The same waterfall with a terminal: called with the event's arguments at the end of the chain, its value what the last `next` gives. */
+  with<T = any>(terminal: (...args: any[]) => any): <U = T>(name: string, ...args: any[]) => U | Promise<U>
+}
+
+/** The plugin API this SDK writes plugins against. */
+export declare const PLUGIN_API: number
+/** The mark on what `definePlugin` makes (`Symbol.for('rutis.leaf-plugin')`), across copies of this package. */
+export declare const PLUGIN: unique symbol
+/** Whether `value` is a plugin `definePlugin` made. */
+export declare function isPlugin(value: unknown): value is Plugin
+
+/** The mark on a value made by `datetime`, `date`, `time`, `decimal` or `uuid` (`Symbol.for('rutis.value')`). */
+export declare const VALUE: unique symbol
+
+/**
+ * A local date and time, date, time of day, decimal or UUID to send as that
+ * value (#308): JavaScript has no type for them. Received, they are strings
+ * (`value`'s text); a plain string is sent as a string.
+ */
+export interface TaggedValue<Tag extends 'datetime' | 'date' | 'time' | 'decimal' | 'uuid'> {
+  readonly [VALUE]: Tag
+  /** The value's text, as it crosses. */
+  readonly value: string
+  toString(): string
+  toJSON(): string
+}
+
+/** A local date and time without a time zone: `'2026-10-15T14:30'`, `'2026-10-15T14:30:05.25'` (years 0001–9999, 0–9 fraction digits). Received as its text. */
+export declare function datetime(text: string): TaggedValue<'datetime'>
+/** A calendar date: `'2026-10-15'` (years 0001–9999). Received as its text. */
+export declare function date(text: string): TaggedValue<'date'>
+/** A time of day without a time zone: `'14:30'`, `'14:30:05.25'` (24-hour). Received as its text. */
+export declare function time(text: string): TaggedValue<'time'>
+/** A decimal number, trailing zeros kept: `'1.10'`, `'-12.3400'` (no exponent, at most 4300 digits). Received as its text. */
+export declare function decimal(text: string | bigint): TaggedValue<'decimal'>
+/** A UUID, `8-4-4-4-12` hex in either case; sent and received in lowercase. */
+export declare function uuid(text: string): TaggedValue<'uuid'>

package/plugins/scheduler/node_modules/@arcships/rutis/src/advanced.mjs

@@ -0,0 +1,32 @@
+// The names a plugin author rarely writes (#692): the plugin API version,
+// the marks the runtimes recognise plugins and values by, and the value
+// constructors. `ctx` and `definePlugin` are in `@arcships/rutis`.
+//
+//   import { datetime, decimal } from '@arcships/rutis/advanced'
+//   return { at: datetime('2026-10-15T14:30'), price: decimal('1.10') }
+
+// The plugin API this SDK writes plugins against. A runtime refuses a plugin
+// that needs a newer one, naming both.
+// 2: ctx.on and ctx.emit (leaf events). A runtime that supports only 1
+// refuses such a plugin at load instead of failing in apply.
+// 3: the unified events of rutis 0.13 (#464): ctx.parallel, serial,
+// waterfall, bail and filter, ctx.signal, and `prepend` / `global` on
+// ctx.on. A runtime of 0.12 or older refuses such a plugin at load.
+export const PLUGIN_API = 3
+
+// Marks what definePlugin returns, across copies of this package.
+export const PLUGIN = Symbol.for('rutis.leaf-plugin')
+
+// Whether `value` is a plugin definePlugin made.
+export const isPlugin = value => value?.[PLUGIN] === true
+
+// Values JavaScript has no type for, to send as what they are (#308): a
+// local date and time, a date, a time of day, a decimal, a UUID. Received,
+// they are strings; a plain string is sent as a string.
+//
+// A Date, Uint8Array, Map, Set and bigint need no constructor: they cross
+// as an instant, bytes, a map, a set and a big integer.
+export { datetime, date, time, decimal, uuid } from './values.mjs'
+// The mark on what they make, across copies of this package and in the
+// runtimes: `Symbol.for('rutis.value')`.
+export { MARK as VALUE } from './values.mjs'

package/plugins/scheduler/node_modules/@arcships/rutis/src/index.d.ts

@@ -0,0 +1,43 @@
+import type * as advanced from './advanced.js'
+
+/**
+ * An error a listener threw arrives, through the host, as an `Error` of the
+ * same built-in class (`TypeError`, `RangeError`, …, `AggregateError`) or a
+ * plain `Error` with the thrower's `name`, `message` and `code`, never as
+ * the thrower's own class: match errors by `name`.
+ */
+export interface Context extends advanced.Emitter {
+  /** The service `name`, which the plugin declares in `inject`: the object itself when a plugin in the same process provides it, else a proxy whose methods are sync or async as declared. */
+  use<T = any>(name: string): T
+  /** Provide `value` as the service `name` until the plugin unloads, or until the returned function is called. It reaches rutis by itself: its methods are the object's functions (own and inherited, not `constructor`), `async` unless `provides` marks them `sync`. */
+  provide(name: string, value: unknown): () => unknown
+  /** Run `cleanup` when the plugin unloads. */
+  effect(cleanup: () => unknown): void
+  /** Aborted when the plugin unloads; its running listeners are then waited for (up to the host's shutdown deadline) before the cleanups run. */
+  readonly signal: AbortSignal
+  /** Listen to `name` on the host's logical bus: every event of that name, from any process or language (a scope is a descriptor). Registered with the host by itself; unregistered when the plugin unloads or the returned function is called. `rutis/*` (the host's framework events) can be listened to; `internal/*` cannot. */
+  on(name: string, listener: advanced.Listener, options?: advanced.ListenerOptions): () => void
+  /** The five ways to emit, delivered only to the listeners `keep` returns true for (`global` listeners are always delivered). `keep` runs in this process, once per candidate, before any listener runs. */
+  filter(keep: (listener: advanced.ListenerDescriptor) => unknown): advanced.Emitter
+}
+
+export interface PluginSpec<C = any> {
+  /** Its name: what listener descriptors (`ListenerDescriptor.plugin`) call it. Without one, they call it by its row's id. */
+  name?: string
+  /** Services the plugin uses: rutis starts it once they are all available, and stops it when one goes. */
+  inject?: string[]
+  /** Optional: services it provides, with the kind of methods to call `sync` (the others are `async`). Without it, what `ctx.provide` provides still reaches rutis; with it, `rutis-host check` knows before the plugin runs. */
+  provides?: Record<string, Record<string, advanced.MethodKind>>
+  /** The JSON Schema of its config. */
+  config?: object
+  apply(ctx: Context, config: C): void | (() => unknown) | Promise<void | (() => unknown)>
+}
+
+export interface Plugin<C = any> extends Readonly<Required<Pick<PluginSpec<C>, 'inject' | 'provides'>>>, Readonly<Omit<PluginSpec<C>, 'inject' | 'provides'>> {
+  /** The plugin API it was written against. */
+  readonly api: number
+  /** Always `true`: what it provides beyond `provides` reaches rutis by itself, known once it runs. */
+  readonly announces: boolean
+}
+
+export declare function definePlugin<C = any>(spec: PluginSpec<C>): Plugin<C>

package/plugins/scheduler/node_modules/@arcships/rutis/src/index.mjs

@@ -0,0 +1,71 @@
+// Write a rutis plugin in JavaScript or TypeScript. A plugin declares the
+// services it uses (`inject`), and `apply(ctx, config)` uses and provides
+// them through `ctx`; rutis decides when it starts, stops and restarts. The
+// runtime that runs it is installed by the host (`@arcships/rutis-runtime`
+// in Node, `@arcships/rutis-bun` in Bun), not by the plugin.
+//
+//   export default definePlugin({
+//     inject: ['llm'],
+//     config: { type: 'object', properties: { city: { type: 'string' } } },
+//     apply(ctx, config) {
+//       ctx.provide('weather', new Weather(ctx.use('llm'), config.city))
+//       ctx.on('weather/ask', city => city === config.city ? 'sunny' : undefined)
+//       return () => {}
+//     },
+//   })
+//
+// Events cross every process and language on the host (#464): `ctx.on`
+// listens to every event of the name on the flat bus, and
+// `ctx.emit` / `parallel` / `serial` / `waterfall` / `bail` reach every
+// listener, wherever it runs, as if all were in this process.
+//
+// What `ctx.provide` provides reaches rutis by itself: its methods are the
+// object's functions (its own and its prototype chain's, not `constructor`),
+// called as `async`. `provides` is optional: `{ weather: { unit: 'sync' } }`
+// marks methods `sync` and tells `rutis-host check` what the plugin
+// provides before it runs.
+
+import { PLUGIN, PLUGIN_API } from './advanced.mjs'
+
+// `config` is a JSON Schema object: the host fills its defaults and checks
+// the config with it before `apply`. A Standard Schema object (schemastery,
+// zod, …) was never applied: refused (config schema design §2.3).
+function checkSchema(config) {
+  const standard = config?.['~standard']
+  if (standard !== undefined) {
+    throw new TypeError(`config of definePlugin should be a JSON Schema object, got ${standard?.vendor === 'schemastery' ? 'a schemastery Schema' : 'a Standard Schema'}`)
+  }
+}
+
+// The module that defined a plugin, as a file URL: the test tool
+// (`@arcships/rutis/testing`) has a real runtime load the plugin from it.
+const FILE = Symbol.for('rutis.plugin-file')
+function definedIn() {
+  const prepare = Error.prepareStackTrace
+  try {
+    Error.prepareStackTrace = (_, sites) => sites
+    const holder = {}
+    Error.captureStackTrace(holder, definePlugin)
+    const file = holder.stack?.[0]?.getFileName?.()
+    return typeof file === 'string' ? file : undefined
+  } catch {
+    return undefined
+  } finally {
+    Error.prepareStackTrace = prepare
+  }
+}
+
+export function definePlugin(spec) {
+  if (typeof spec?.apply !== 'function') throw new TypeError('a plugin needs apply(ctx, config)')
+  checkSchema(spec.config)
+  const inject = spec.inject ?? []
+  if (!Array.isArray(inject) || inject.some(name => typeof name !== 'string')) throw new TypeError('inject must be a list of service names')
+  for (const [name, methods] of Object.entries(spec.provides ?? {})) {
+    for (const [method, kind] of Object.entries(methods ?? {})) {
+      if (kind !== 'sync' && kind !== 'async') throw new TypeError(`${name}.${method}: kind must be 'sync' or 'async'`)
+    }
+  }
+  // `announces`: what it provides beyond `provides` (all of it, without
+  // one) reaches rutis by itself, and is known once it runs.
+  return Object.freeze({ ...spec, inject, provides: spec.provides ?? {}, announces: true, api: PLUGIN_API, [PLUGIN]: true, [FILE]: definedIn() })
+}