@raisindb/function-assemblyscript 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# @raisindb/function-assemblyscript
+
+Write a RaisinDB server function in AssemblyScript and ship it as a WebAssembly
+component — TypeScript-shaped syntax, no embedded JavaScript engine, artifacts
+measured in kilobytes.
+
+```bash
+raisindb create function greet --lang assemblyscript --ns demo
+raisindb function build wasm/demo/greet
+raisindb function run   wasm/demo/greet --input '{"name":"Ada"}'
+```
+
+## Writing a handler
+
+```ts
+import { run, log, nodes, unknownHandler, cabi_realloc } from "@raisindb/function-assemblyscript";
+
+function greet(input: string): string {
+  log.info("greeting");
+  const children = nodes.getChildren("content", "/pages", 50);
+  return '{"greeting":"hello","pages":' + children.length.toString() + "}";
+}
+
+// The component exports ONE function; the node's `entry_file` suffix picks the
+// handler, so routing is an ordinary switch.
+function route(name: string, input: string): string {
+  if (name == "default") return greet(input);
+  return unknownHandler(name, "default");
+}
+
+export function handler(np: i32, nl: i32, ip: i32, il: i32): i32 {
+  return run(np, nl, ip, il, route);
+}
+export { cabi_realloc };
+```
+
+`handler` and `cabi_realloc` must both be exported from the entry module:
+`wasm-tools component new` looks them up by name.
+
+## Why the lowering is hand-written
+
+AssemblyScript deliberately does not implement WASI or the Component Model and
+has no `wit-bindgen` backend, so `asc` produces a core module while the host
+requires a component. `assembly/abi.ts` is the bridge — the only file that
+knows about pointers — and `raisindb function build` runs
+`asc` → `wasm-tools component embed` → `wasm-tools component new`.
+
+Two ABI details it exists to get right, both of which fail silently:
+
+* An imported interface is named with its package version,
+  `raisin:function/host@0.1.0`.
+* A variant discriminant is a `u8` padded to the payload's alignment, so
+  `result<string, string>` is `{ u8 tag, 3 pad, i32 ptr, i32 len }`. Read as an
+  `i32` the tag picks up padding and every `Ok` looks like an `Err` — with the
+  payload still decoding correctly.
+
+## Strings, not objects
+
+Handlers take and return JSON **strings**. AssemblyScript has no built-in JSON,
+and bundling one would make every artifact pay for it. Use
+[`json-as`](https://github.com/JairusSW/as-json) if you want typed
+(de)serialisation, or build strings directly for simple outputs.

package/assembly/abi.ts

@@ -0,0 +1,154 @@
+// Canonical-ABI plumbing for the RaisinDB guest world.
+//
+// AssemblyScript does not implement the Component Model, so this file is what
+// `wit-bindgen` would emit for a supported language: the lowering between
+// AssemblyScript values and the ABI `wasm-tools component new` expects. It is
+// the only file in this SDK that knows about pointers, and the only one anyone
+// should need to review when the WIT world changes.
+//
+// Two rules it exists to get right, both of which fail QUIETLY when wrong:
+//
+//  1. An imported interface is named WITH ITS PACKAGE VERSION —
+//     `raisin:function/host@0.1.0`. Without it, componentization refuses to
+//     resolve the import.
+//  2. A variant discriminant is stored in the SMALLEST integer that fits its
+//     case count, then padded to the payload's alignment. `result<string,
+//     string>` is therefore `{ u8 tag, 3 bytes padding, i32 ptr, i32 len }`.
+//     Reading the tag as an i32 picks up padding and turns every Ok into an
+//     Err while the payload still decodes perfectly — a failure that looks
+//     like the host misbehaving rather than like a guest bug.
+
+// --- host imports -----------------------------------------------------------
+
+@external("raisin:function/host@0.1.0", "call")
+declare function hostCall(mp: i32, ml: i32, ap: i32, al: i32, ret: i32): void;
+
+@external("raisin:function/host@0.1.0", "log")
+declare function hostLog(level: i32, mp: i32, ml: i32): void;
+
+@external("raisin:function/host@0.1.0", "context")
+declare function hostContext(ret: i32): void;
+
+@external("raisin:function/host@0.1.0", "abi-version")
+declare function hostAbiVersion(ret: i32): void;
+
+// --- memory -----------------------------------------------------------------
+
+/**
+ * The host allocates into guest memory through this.
+ * `wasm-tools component new` looks it up BY NAME, so it must be re-exported
+ * from the guest's entry module.
+ */
+export function cabi_realloc(oldPtr: i32, oldSize: i32, align: i32, newSize: i32): i32 {
+  if (newSize == 0) return align;
+  const p = heap.alloc(<usize>newSize);
+  if (oldPtr != 0 && oldSize > 0) {
+    memory.copy(p, <usize>oldPtr, <usize>(oldSize < newSize ? oldSize : newSize));
+  }
+  return <i32>p;
+}
+
+/** A UTF-8 copy of `s` in linear memory that outlives this call. */
+function encode(s: string): usize {
+  const buf = String.UTF8.encode(s);
+  const p = heap.alloc(<usize>buf.byteLength);
+  memory.copy(p, changetype<usize>(buf), <usize>buf.byteLength);
+  return p;
+}
+
+function byteLen(s: string): i32 {
+  return <i32>String.UTF8.byteLength(s);
+}
+
+function decode(ptr: i32, len: i32): string {
+  if (len <= 0) return "";
+  return String.UTF8.decodeUnsafe(<usize>ptr, <usize>len, false);
+}
+
+// --- host calls -------------------------------------------------------------
+
+/** Raised when the host answers a `call` with the error arm. */
+export class HostError {
+  constructor(public message: string) {}
+}
+
+/**
+ * Invoke a RaisinDB API method by its registry name, e.g. `nodes_getChildren`.
+ * `argsJson` is a JSON array of positional arguments.
+ *
+ * Returns the raw JSON the host produced. Throws `HostError` on the error arm.
+ */
+export function call(method: string, argsJson: string): string {
+  const area = heap.alloc(12);
+  hostCall(<i32>encode(method), byteLen(method), <i32>encode(argsJson), byteLen(argsJson), <i32>area);
+  const tag = load<u8>(area); // u8 — see the header
+  const body = decode(load<i32>(area + 4), load<i32>(area + 8));
+  if (tag != 0) throw new HostError(body);
+  return body;
+}
+
+export namespace log {
+  export function debug(message: string): void { emit(0, message); }
+  export function info(message: string): void { emit(1, message); }
+  export function warn(message: string): void { emit(2, message); }
+  export function error(message: string): void { emit(3, message); }
+  function emit(level: i32, message: string): void {
+    hostLog(level, <i32>encode(message), byteLen(message));
+  }
+}
+
+/** The execution context as JSON — tenant, repo, branch, actor, execution id. */
+export function context(): string {
+  const area = heap.alloc(8);
+  hostContext(<i32>area);
+  return decode(load<i32>(area), load<i32>(area + 4));
+}
+
+/** The host ABI version this server speaks, e.g. "0.1.0". */
+export function abiVersion(): string {
+  const area = heap.alloc(8);
+  hostAbiVersion(<i32>area);
+  return decode(load<i32>(area), load<i32>(area + 4));
+}
+
+// --- the exported handler ---------------------------------------------------
+
+/** A handler: takes the JSON input, returns the JSON output. */
+export type Route = (name: string, input: string) => string;
+
+let RET: usize = 0;
+
+function finish(tag: u8, body: string): i32 {
+  if (!RET) RET = heap.alloc(12);
+  store<u8>(RET, tag);
+  store<u8>(RET + 1, 0);
+  store<u8>(RET + 2, 0);
+  store<u8>(RET + 3, 0);
+  store<i32>(RET + 4, <i32>encode(body));
+  store<i32>(RET + 8, byteLen(body));
+  return <i32>RET;
+}
+
+/**
+ * Lower the exported `handler(name, input) -> result<string, string>`.
+ *
+ * A guest's entry module re-exports this as `handler` and hands it a router.
+ * A `HostError` (or any thrown error) becomes the ABI's error arm rather than
+ * a trap, so a failing API call reports a message instead of killing the
+ * instance.
+ */
+export function run(
+  namePtr: i32, nameLen: i32, inputPtr: i32, inputLen: i32, route: Route
+): i32 {
+  const name = decode(namePtr, nameLen);
+  const input = decode(inputPtr, inputLen);
+  let out: string;
+  if (name.length == 0) return finish(1, "handler name was empty");
+  out = route(name, input);
+  return finish(0, out);
+}
+
+/** The error a router should return for a name it does not know. */
+export function unknownHandler(name: string, registered: string): string {
+  return '{"error":"unknown handler ' + name + '; registered: ' + registered + '"}';
+}

package/assembly/generated.ts

@@ -0,0 +1,690 @@
+// Code generated by `cargo run -p raisin-functions --bin gen-bindings`.
+// DO NOT EDIT — edit `crates/raisin-functions/src/runtime/bindings/` and
+// re-run `make gen-bindings` instead.
+
+import { call } from "./abi";
+
+// --- JSON argument helpers -------------------------------------------------
+// AssemblyScript ships no JSON encoder, so the few shapes the gateway needs
+// are built here rather than pulling a library into every artifact.
+
+function jsonString(s: string): string {
+  let out = "\"";
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c == 0x22) out += "\\\"";
+    else if (c == 0x5c) out += "\\\\";
+    else if (c == 0x0a) out += "\\n";
+    else if (c == 0x0d) out += "\\r";
+    else if (c == 0x09) out += "\\t";
+    else if (c < 0x20) out += "\\u" + c.toString(16).padStart(4, "0");
+    else out += String.fromCharCode(c);
+  }
+  return out + "\"";
+}
+
+function jsonStringOrNull(s: string | null): string {
+  return s == null ? "null" : jsonString(s!);
+}
+
+function jsonStringArray(items: string[]): string {
+  let out = "[";
+  for (let i = 0; i < items.length; i++) {
+    if (i > 0) out += ",";
+    out += jsonString(items[i]);
+  }
+  return out + "]";
+}
+
+function argsOf(parts: string[]): string {
+  let out = "[";
+  for (let i = 0; i < parts.length; i++) {
+    if (i > 0) out += ",";
+    out += parts[i];
+  }
+  return out + "]";
+}
+
+export namespace admin {
+export namespace nodes {
+  /** `raisin.admin.nodes.create` — registry method `admin_nodes_create`. Returns raw JSON. */
+  export function create(workspace: string, parentPath: string, data: string): string {
+    return call("admin_nodes_create", argsOf([jsonString(workspace), jsonString(parentPath), data]));
+  }
+
+  /** `raisin.admin.nodes.delete` — registry method `admin_nodes_delete`. Returns raw JSON. */
+  export function delete_(workspace: string, path: string): string {
+    return call("admin_nodes_delete", argsOf([jsonString(workspace), jsonString(path)]));
+  }
+
+  /** `raisin.admin.nodes.get` — registry method `admin_nodes_get`. Returns raw JSON. */
+  export function get(workspace: string, path: string): string {
+    return call("admin_nodes_get", argsOf([jsonString(workspace), jsonString(path)]));
+  }
+
+  /** `raisin.admin.nodes.getById` — registry method `admin_nodes_getById`. Returns raw JSON. */
+  export function getById(workspace: string, id: string): string {
+    return call("admin_nodes_getById", argsOf([jsonString(workspace), jsonString(id)]));
+  }
+
+  /** `raisin.admin.nodes.getChildren` — registry method `admin_nodes_getChildren`. Returns raw JSON. */
+  export function getChildren(workspace: string, parentPath: string, limit: i64): string {
+    return call("admin_nodes_getChildren", argsOf([jsonString(workspace), jsonString(parentPath), (limit < 0 ? "null" : limit.toString())]));
+  }
+
+  /** `raisin.admin.nodes.query` — registry method `admin_nodes_query`. Returns raw JSON. */
+  export function query(workspace: string, query: string): string {
+    return call("admin_nodes_query", argsOf([jsonString(workspace), query]));
+  }
+
+  /** `raisin.admin.nodes.update` — registry method `admin_nodes_update`. Returns raw JSON. */
+  export function update(workspace: string, path: string, data: string): string {
+    return call("admin_nodes_update", argsOf([jsonString(workspace), jsonString(path), data]));
+  }
+
+  /** `raisin.admin.nodes.updateProperty` — registry method `admin_nodes_updateProperty`. Returns raw JSON. */
+  export function updateProperty(workspace: string, nodePath: string, propertyPath: string, value: string): string {
+    return call("admin_nodes_updateProperty", argsOf([jsonString(workspace), jsonString(nodePath), jsonString(propertyPath), value]));
+  }
+
+}
+}
+
+export namespace admin {
+export namespace sql {
+  /** `raisin.admin.sql.execute` — registry method `admin_sql_execute`. Returns raw JSON. */
+  export function execute(sql: string, params: string): string {
+    return call("admin_sql_execute", argsOf([jsonString(sql), params]));
+  }
+
+  /** `raisin.admin.sql.query` — registry method `admin_sql_query`. Returns raw JSON. */
+  export function query(sql: string, params: string): string {
+    return call("admin_sql_query", argsOf([jsonString(sql), params]));
+  }
+
+}
+}
+
+export namespace ai {
+  /** `raisin.ai.completion` — registry method `ai_completion`. Returns raw JSON. */
+  export function completion(request: string): string {
+    return call("ai_completion", argsOf([request]));
+  }
+
+  /** `raisin.ai.embed` — registry method `ai_embed`. Returns raw JSON. */
+  export function embed(request: string): string {
+    return call("ai_embed", argsOf([request]));
+  }
+
+  /** `raisin.ai.getDefaultModel` — registry method `ai_getDefaultModel`. Returns raw JSON. */
+  export function getDefaultModel(useCase: string): string {
+    return call("ai_getDefaultModel", argsOf([jsonString(useCase)]));
+  }
+
+  /** `raisin.ai.listModels` — registry method `ai_listModels`. Returns raw JSON. */
+  export function listModels(): string {
+    return call("ai_listModels", "[]");
+  }
+
+  /** `raisin.ai.listProviders` — registry method `ai_listProviders`. Returns raw JSON. */
+  export function listProviders(): string {
+    return call("ai_listProviders", "[]");
+  }
+
+}
+
+export namespace assets {
+  /** `raisin.assets.ensureContent` — registry method `asset_ensure_content`. Returns raw JSON. */
+  export function ensureContent(workspace: string, nodeRef: string): string {
+    return call("asset_ensure_content", argsOf([jsonString(workspace), jsonString(nodeRef)]));
+  }
+
+  /** `raisin.assets.reextract` — registry method `asset_reextract`. Returns raw JSON. */
+  export function reextract(workspace: string, nodeRef: string): string {
+    return call("asset_reextract", argsOf([jsonString(workspace), jsonString(nodeRef)]));
+  }
+
+  /** `raisin.assets.setExtractedText` — registry method `asset_set_extraction`. Returns raw JSON. */
+  export function setExtractedText(workspace: string, nodeRef: string, text: string, options: string): string {
+    return call("asset_set_extraction", argsOf([jsonString(workspace), jsonString(nodeRef), jsonString(text), options]));
+  }
+
+  /** `raisin.assets.signedUrl` — registry method `asset_signed_url`. Returns raw JSON. */
+  export function signedUrl(workspace: string, nodeRef: string, options: string): string {
+    return call("asset_signed_url", argsOf([jsonString(workspace), jsonString(nodeRef), options]));
+  }
+
+}
+
+export namespace branches {
+  /** `raisin.branches.compare` — registry method `branches_compare`. Returns raw JSON. */
+  export function compare(branch: string, baseBranch: string): string {
+    return call("branches_compare", argsOf([jsonString(branch), jsonString(baseBranch)]));
+  }
+
+  /** `raisin.branches.copyNodes` — registry method `branches_copyNodes`. Returns raw JSON. */
+  export function copyNodes(sourceBranch: string, targetBranch: string, opts: string): string {
+    return call("branches_copyNodes", argsOf([jsonString(sourceBranch), jsonString(targetBranch), opts]));
+  }
+
+  /** `raisin.branches.diff` — registry method `branches_diff`. Returns raw JSON. */
+  export function diff(branch: string, baseBranch: string): string {
+    return call("branches_diff", argsOf([jsonString(branch), jsonString(baseBranch)]));
+  }
+
+}
+
+export namespace crypto {
+  /** `raisin.crypto.generateKeyPair` — registry method `crypto_generate_key_pair`. Returns raw JSON. */
+  export function generateKeyPair(alg: string | null): string {
+    return call("crypto_generate_key_pair", argsOf([jsonStringOrNull(alg)]));
+  }
+
+  /** `raisin.crypto.hash` — registry method `crypto_hash`. Returns raw JSON. */
+  export function hash(input: string, alg: string | null): string {
+    return call("crypto_hash", argsOf([jsonString(input), jsonStringOrNull(alg)]));
+  }
+
+  /** `raisin.crypto.randomBytes` — registry method `crypto_random_bytes`. Returns raw JSON. */
+  export function randomBytes(n: u32): string {
+    return call("crypto_random_bytes", argsOf([n.toString()]));
+  }
+
+  /** `raisin.crypto.signJwt` — registry method `crypto_sign_jwt`. Returns raw JSON. */
+  export function signJwt(claims: string, private_jwk: string, opts: string | null): string {
+    return call("crypto_sign_jwt", argsOf([claims, private_jwk, (opts == null ? "null" : opts!)]));
+  }
+
+  /** `raisin.crypto.uuid` — registry method `crypto_uuid`. Returns raw JSON. */
+  export function uuid(): string {
+    return call("crypto_uuid", "[]");
+  }
+
+  /** `raisin.crypto.verifyJwt` — registry method `crypto_verify_jwt`. Returns raw JSON. */
+  export function verifyJwt(token: string, opts: string | null): string {
+    return call("crypto_verify_jwt", argsOf([jsonString(token), (opts == null ? "null" : opts!)]));
+  }
+
+}
+
+export namespace date {
+  /** `raisin.date.addDays` — registry method `date_addDays`. Returns raw JSON. */
+  export function addDays(timestamp: i64, days: i64): string {
+    return call("date_addDays", argsOf([timestamp.toString(), days.toString()]));
+  }
+
+  /** `raisin.date.diffDays` — registry method `date_diffDays`. Returns raw JSON. */
+  export function diffDays(ts1: i64, ts2: i64): string {
+    return call("date_diffDays", argsOf([ts1.toString(), ts2.toString()]));
+  }
+
+  /** `raisin.date.format` — registry method `date_format`. Returns raw JSON. */
+  export function format(timestamp: i64, format: string | null): string {
+    return call("date_format", argsOf([timestamp.toString(), jsonStringOrNull(format)]));
+  }
+
+  /** `raisin.date.now` — registry method `date_now`. Returns raw JSON. */
+  export function now(): string {
+    return call("date_now", "[]");
+  }
+
+  /** `raisin.date.parse` — registry method `date_parse`. Returns raw JSON. */
+  export function parse(dateStr: string, format: string | null): string {
+    return call("date_parse", argsOf([jsonString(dateStr), jsonStringOrNull(format)]));
+  }
+
+  /** `raisin.date.timestamp` — registry method `date_timestamp`. Returns raw JSON. */
+  export function timestamp(): string {
+    return call("date_timestamp", "[]");
+  }
+
+  /** `raisin.date.timestampMillis` — registry method `date_timestampMillis`. Returns raw JSON. */
+  export function timestampMillis(): string {
+    return call("date_timestampMillis", "[]");
+  }
+
+}
+
+export namespace email {
+  /** `raisin.email.providers` — registry method `email_providers`. Returns raw JSON. */
+  export function providers(): string {
+    return call("email_providers", "[]");
+  }
+
+  /** `raisin.email.send` — registry method `email_send`. Returns raw JSON. */
+  export function send(message: string): string {
+    return call("email_send", argsOf([message]));
+  }
+
+}
+
+export namespace events {
+  /** `raisin.events.emit` — registry method `events_emit`. Returns raw JSON. */
+  export function emit(eventType: string, data: string): string {
+    return call("events_emit", argsOf([jsonString(eventType), data]));
+  }
+
+}
+
+export namespace flows {
+  /** `raisin.flows.run` — registry method `flows_run`. Returns raw JSON. */
+  export function run(flowPath: string, input: string): string {
+    return call("flows_run", argsOf([jsonString(flowPath), input]));
+  }
+
+}
+
+export namespace functions {
+  /** `raisin.functions.call` — registry method `functions_call`. Returns raw JSON. */
+  export function call(functionPath: string, arguments: string): string {
+    return call("functions_call", argsOf([jsonString(functionPath), arguments]));
+  }
+
+  /** `raisin.functions.execute` — registry method `functions_execute`. Returns raw JSON. */
+  export function execute(functionPath: string, arguments: string, context: string): string {
+    return call("functions_execute", argsOf([jsonString(functionPath), arguments, context]));
+  }
+
+}
+
+export namespace http {
+  /** `raisin.http.request` — registry method `http_request`. Returns raw JSON. */
+  export function request(method: string, url: string, options: string): string {
+    return call("http_request", argsOf([jsonString(method), jsonString(url), options]));
+  }
+
+}
+
+export namespace identities {
+  /** `raisin.identities.findByEmail` — registry method `identities_findByEmail`. Returns raw JSON. */
+  export function findByEmail(email: string): string {
+    return call("identities_findByEmail", argsOf([jsonString(email)]));
+  }
+
+  /** `raisin.identities.update` — registry method `identities_update`. Returns raw JSON. */
+  export function update(id: string, patch: string): string {
+    return call("identities_update", argsOf([jsonString(id), patch]));
+  }
+
+}
+
+export namespace imap {
+  /** `raisin.imap.fetchMessage` — registry method `imap_fetch_message`. Returns raw JSON. */
+  export function fetchMessage(conn: string, uid: i64, opts: string | null): string {
+    return call("imap_fetch_message", argsOf([conn, uid.toString(), (opts == null ? "null" : opts!)]));
+  }
+
+  /** `raisin.imap.fetchSince` — registry method `imap_fetch_since`. Returns raw JSON. */
+  export function fetchSince(conn: string, sinceUid: i64, opts: string | null): string {
+    return call("imap_fetch_since", argsOf([conn, sinceUid.toString(), (opts == null ? "null" : opts!)]));
+  }
+
+  /** `raisin.imap.listMailboxes` — registry method `imap_list_mailboxes`. Returns raw JSON. */
+  export function listMailboxes(conn: string): string {
+    return call("imap_list_mailboxes", argsOf([conn]));
+  }
+
+}
+
+export namespace integrations {
+  /** `raisin.integrations.syncNow` — registry method `integrations_sync_now`. Returns raw JSON. */
+  export function syncNow(mountId: string, mode: string | null): string {
+    return call("integrations_sync_now", argsOf([jsonString(mountId), jsonStringOrNull(mode)]));
+  }
+
+}
+
+export namespace inventory {
+  /** `raisin.inventory.claim` — registry method `inventory_claim`. Returns raw JSON. */
+  export function claim(pool: string, n: i64, capacity: i64): string {
+    return call("inventory_claim", argsOf([jsonString(pool), n.toString(), capacity.toString()]));
+  }
+
+  /** `raisin.inventory.release` — registry method `inventory_release`. Returns raw JSON. */
+  export function release(pool: string, n: i64): string {
+    return call("inventory_release", argsOf([jsonString(pool), n.toString()]));
+  }
+
+}
+
+export namespace locks {
+  /** `raisin.locks.acquire` — registry method `locks_acquire`. Returns raw JSON. */
+  export function acquire(key: string, ttlMs: i64, owner: string | null): string {
+    return call("locks_acquire", argsOf([jsonString(key), ttlMs.toString(), jsonStringOrNull(owner)]));
+  }
+
+  /** `raisin.locks.release` — registry method `locks_release`. Returns raw JSON. */
+  export function release(key: string, token: i64): string {
+    return call("locks_release", argsOf([jsonString(key), token.toString()]));
+  }
+
+  /** `raisin.locks.renew` — registry method `locks_renew`. Returns raw JSON. */
+  export function renew(key: string, token: i64, ttlMs: i64): string {
+    return call("locks_renew", argsOf([jsonString(key), token.toString(), ttlMs.toString()]));
+  }
+
+}
+
+export namespace nodes {
+  /** `raisin.nodes.addResource` — registry method `nodes_addResource`. Returns raw JSON. */
+  export function addResource(workspace: string, nodePath: string, propertyPath: string, uploadData: string): string {
+    return call("nodes_addResource", argsOf([jsonString(workspace), jsonString(nodePath), jsonString(propertyPath), uploadData]));
+  }
+
+  /** `raisin.nodes.applyChildOrder` — registry method `nodes_applyChildOrder`. Returns raw JSON. */
+  export function applyChildOrder(workspace: string, parentPath: string, sourceBranch: string, targetBranch: string): string {
+    return call("nodes_applyChildOrder", argsOf([jsonString(workspace), jsonString(parentPath), jsonString(sourceBranch), jsonString(targetBranch)]));
+  }
+
+  /** `raisin.nodes.create` — registry method `nodes_create`. Returns raw JSON. */
+  export function create(workspace: string, parentPath: string, data: string): string {
+    return call("nodes_create", argsOf([jsonString(workspace), jsonString(parentPath), data]));
+  }
+
+  /** `raisin.nodes.delete` — registry method `nodes_delete`. Returns raw JSON. */
+  export function delete_(workspace: string, path: string): string {
+    return call("nodes_delete", argsOf([jsonString(workspace), jsonString(path)]));
+  }
+
+  /** `raisin.nodes.get` — registry method `nodes_get`. Returns raw JSON. */
+  export function get(workspace: string, path: string): string {
+    return call("nodes_get", argsOf([jsonString(workspace), jsonString(path)]));
+  }
+
+  /** `raisin.nodes.getById` — registry method `nodes_getById`. Returns raw JSON. */
+  export function getById(workspace: string, id: string): string {
+    return call("nodes_getById", argsOf([jsonString(workspace), jsonString(id)]));
+  }
+
+  /** `raisin.nodes.getChildren` — registry method `nodes_getChildren`. Returns raw JSON. */
+  export function getChildren(workspace: string, parentPath: string, limit: i64): string {
+    return call("nodes_getChildren", argsOf([jsonString(workspace), jsonString(parentPath), (limit < 0 ? "null" : limit.toString())]));
+  }
+
+  /** `raisin.nodes.history` — registry method `nodes_history`. Returns raw JSON. */
+  export function history(workspace: string, id: string, limit: i64): string {
+    return call("nodes_history", argsOf([jsonString(workspace), jsonString(id), (limit < 0 ? "null" : limit.toString())]));
+  }
+
+  /** `raisin.nodes.move` — registry method `nodes_move`. Returns raw JSON. */
+  export function move(workspace: string, nodePath: string, newParentPath: string): string {
+    return call("nodes_move", argsOf([jsonString(workspace), jsonString(nodePath), jsonString(newParentPath)]));
+  }
+
+  /** `raisin.nodes.moveChildAfter` — registry method `nodes_moveChildAfter`. Returns raw JSON. */
+  export function moveChildAfter(workspace: string, parentPath: string, childName: string, afterChildName: string): string {
+    return call("nodes_moveChildAfter", argsOf([jsonString(workspace), jsonString(parentPath), jsonString(childName), jsonString(afterChildName)]));
+  }
+
+  /** `raisin.nodes.moveChildBefore` — registry method `nodes_moveChildBefore`. Returns raw JSON. */
+  export function moveChildBefore(workspace: string, parentPath: string, childName: string, beforeChildName: string): string {
+    return call("nodes_moveChildBefore", argsOf([jsonString(workspace), jsonString(parentPath), jsonString(childName), jsonString(beforeChildName)]));
+  }
+
+  /** `raisin.nodes.query` — registry method `nodes_query`. Returns raw JSON. */
+  export function query(workspace: string, query: string): string {
+    return call("nodes_query", argsOf([jsonString(workspace), query]));
+  }
+
+  /** `raisin.nodes.reorderChild` — registry method `nodes_reorderChild`. Returns raw JSON. */
+  export function reorderChild(workspace: string, parentPath: string, childName: string, position: u32): string {
+    return call("nodes_reorderChild", argsOf([jsonString(workspace), jsonString(parentPath), jsonString(childName), position.toString()]));
+  }
+
+  /** `raisin.nodes.update` — registry method `nodes_update`. Returns raw JSON. */
+  export function update(workspace: string, path: string, data: string): string {
+    return call("nodes_update", argsOf([jsonString(workspace), jsonString(path), data]));
+  }
+
+  /** `raisin.nodes.updateProperty` — registry method `nodes_updateProperty`. Returns raw JSON. */
+  export function updateProperty(workspace: string, nodePath: string, propertyPath: string, value: string): string {
+    return call("nodes_updateProperty", argsOf([jsonString(workspace), jsonString(nodePath), jsonString(propertyPath), value]));
+  }
+
+}
+
+export namespace notify {
+  /** `raisin.notify.notify` — registry method `notify_send`. Returns raw JSON. */
+  export function notify(options: string): string {
+    return call("notify_send", argsOf([options]));
+  }
+
+}
+
+export namespace ocr {
+  /** `raisin.ocr.image` — registry method `ocr_image`. Returns raw JSON. */
+  export function image(base64Data: string, options: string): string {
+    return call("ocr_image", argsOf([jsonString(base64Data), options]));
+  }
+
+}
+
+export namespace pdf {
+  /** `raisin.pdf.extractText` — registry method `pdf_extractText`. Returns raw JSON. */
+  export function extractText(base64Data: string): string {
+    return call("pdf_extractText", argsOf([jsonString(base64Data)]));
+  }
+
+  /** `raisin.pdf.getPageCount` — registry method `pdf_getPageCount`. Returns raw JSON. */
+  export function getPageCount(base64Data: string): string {
+    return call("pdf_getPageCount", argsOf([jsonString(base64Data)]));
+  }
+
+  /** `raisin.pdf.ocr` — registry method `pdf_ocr`. Returns raw JSON. */
+  export function ocr(base64Data: string, options: string): string {
+    return call("pdf_ocr", argsOf([jsonString(base64Data), options]));
+  }
+
+  /** `raisin.pdf.processFromStorage` — registry method `pdf_processFromStorage`. Returns raw JSON. */
+  export function processFromStorage(storageKey: string, options: string): string {
+    return call("pdf_processFromStorage", argsOf([jsonString(storageKey), options]));
+  }
+
+}
+
+export namespace platform {
+  /** `raisin.platform.hook` — registry method `platform_hook`. Returns raw JSON. */
+  export function hook(name: string, payload: string): string {
+    return call("platform_hook", argsOf([jsonString(name), payload]));
+  }
+
+}
+
+export namespace resources {
+  /** `raisin.resources.getBinary` — registry method `resources_getBinary`. Returns raw JSON. */
+  export function getBinary(storageKey: string): string {
+    return call("resources_getBinary", argsOf([jsonString(storageKey)]));
+  }
+
+}
+
+export namespace scheduler {
+  /** `raisin.scheduler.cancel` — registry method `scheduler_cancel`. Returns raw JSON. */
+  export function cancel(jobIdOrKey: string): string {
+    return call("scheduler_cancel", argsOf([jsonString(jobIdOrKey)]));
+  }
+
+  /** `raisin.scheduler.get` — registry method `scheduler_get`. Returns raw JSON. */
+  export function get(jobIdOrKey: string): string {
+    return call("scheduler_get", argsOf([jsonString(jobIdOrKey)]));
+  }
+
+  /** `raisin.scheduler.list` — registry method `scheduler_list`. Returns raw JSON. */
+  export function list(filter: string | null): string {
+    return call("scheduler_list", argsOf([(filter == null ? "null" : filter!)]));
+  }
+
+  /** `raisin.scheduler.schedule` — registry method `scheduler_schedule`. Returns raw JSON. */
+  export function schedule(request: string): string {
+    return call("scheduler_schedule", argsOf([request]));
+  }
+
+}
+
+export namespace secrets {
+  /** `raisin.secrets.delete` — registry method `secrets_delete`. Returns raw JSON. */
+  export function delete_(name: string): string {
+    return call("secrets_delete", argsOf([jsonString(name)]));
+  }
+
+  /** `raisin.secrets.get` — registry method `secrets_get`. Returns raw JSON. */
+  export function get(name: string, version: i64): string {
+    return call("secrets_get", argsOf([jsonString(name), (version < 0 ? "null" : version.toString())]));
+  }
+
+  /** `raisin.secrets.list` — registry method `secrets_list`. Returns raw JSON. */
+  export function list(): string {
+    return call("secrets_list", "[]");
+  }
+
+  /** `raisin.secrets.put` — registry method `secrets_put`. Returns raw JSON. */
+  export function put(name: string, value: string): string {
+    return call("secrets_put", argsOf([jsonString(name), jsonString(value)]));
+  }
+
+  /** `raisin.secrets.resolve` — registry method `secrets_resolve`. Returns raw JSON. */
+  export function resolve(value: string): string {
+    return call("secrets_resolve", argsOf([jsonString(value)]));
+  }
+
+  /** `raisin.secrets.rotate` — registry method `secrets_rotate`. Returns raw JSON. */
+  export function rotate(name: string, value: string): string {
+    return call("secrets_rotate", argsOf([jsonString(name), jsonString(value)]));
+  }
+
+}
+
+export namespace sql {
+  /** `raisin.sql.execute` — registry method `sql_execute`. Returns raw JSON. */
+  export function execute(sql: string, params: string): string {
+    return call("sql_execute", argsOf([jsonString(sql), params]));
+  }
+
+  /** `raisin.sql.query` — registry method `sql_query`. Returns raw JSON. */
+  export function query(sql: string, params: string): string {
+    return call("sql_query", argsOf([jsonString(sql), params]));
+  }
+
+}
+
+export namespace tasks {
+  /** `raisin.tasks.complete` — registry method `tasks_complete`. Returns raw JSON. */
+  export function complete(task_id: string, response: string): string {
+    return call("tasks_complete", argsOf([jsonString(task_id), response]));
+  }
+
+  /** `raisin.tasks.create` — registry method `tasks_create`. Returns raw JSON. */
+  export function create(request: string): string {
+    return call("tasks_create", argsOf([request]));
+  }
+
+  /** `raisin.tasks.query` — registry method `tasks_query`. Returns raw JSON. */
+  export function query(query: string): string {
+    return call("tasks_query", argsOf([query]));
+  }
+
+  /** `raisin.tasks.update` — registry method `tasks_update`. Returns raw JSON. */
+  export function update(task_id: string, updates: string): string {
+    return call("tasks_update", argsOf([jsonString(task_id), updates]));
+  }
+
+}
+
+export namespace tx {
+  /** `raisin.tx.add` — registry method `tx_add`. Returns raw JSON. */
+  export function add(txId: string, workspace: string, data: string): string {
+    return call("tx_add", argsOf([jsonString(txId), jsonString(workspace), data]));
+  }
+
+  /** `raisin.tx.begin` — registry method `tx_begin`. Returns raw JSON. */
+  export function begin(): string {
+    return call("tx_begin", "[]");
+  }
+
+  /** `raisin.tx.commit` — registry method `tx_commit`. Returns raw JSON. */
+  export function commit(txId: string): string {
+    return call("tx_commit", argsOf([jsonString(txId)]));
+  }
+
+  /** `raisin.tx.create` — registry method `tx_create`. Returns raw JSON. */
+  export function create(txId: string, workspace: string, parentPath: string, data: string): string {
+    return call("tx_create", argsOf([jsonString(txId), jsonString(workspace), jsonString(parentPath), data]));
+  }
+
+  /** `raisin.tx.createDeep` — registry method `tx_createDeep`. Returns raw JSON. */
+  export function createDeep(txId: string, workspace: string, parentPath: string, data: string, parentNodeType: string): string {
+    return call("tx_createDeep", argsOf([jsonString(txId), jsonString(workspace), jsonString(parentPath), data, jsonString(parentNodeType)]));
+  }
+
+  /** `raisin.tx.delete` — registry method `tx_delete`. Returns raw JSON. */
+  export function delete_(txId: string, workspace: string, path: string): string {
+    return call("tx_delete", argsOf([jsonString(txId), jsonString(workspace), jsonString(path)]));
+  }
+
+  /** `raisin.tx.deleteById` — registry method `tx_deleteById`. Returns raw JSON. */
+  export function deleteById(txId: string, workspace: string, id: string): string {
+    return call("tx_deleteById", argsOf([jsonString(txId), jsonString(workspace), jsonString(id)]));
+  }
+
+  /** `raisin.tx.get` — registry method `tx_get`. Returns raw JSON. */
+  export function get(txId: string, workspace: string, id: string): string {
+    return call("tx_get", argsOf([jsonString(txId), jsonString(workspace), jsonString(id)]));
+  }
+
+  /** `raisin.tx.getByPath` — registry method `tx_getByPath`. Returns raw JSON. */
+  export function getByPath(txId: string, workspace: string, path: string): string {
+    return call("tx_getByPath", argsOf([jsonString(txId), jsonString(workspace), jsonString(path)]));
+  }
+
+  /** `raisin.tx.listChildren` — registry method `tx_listChildren`. Returns raw JSON. */
+  export function listChildren(txId: string, workspace: string, parentPath: string): string {
+    return call("tx_listChildren", argsOf([jsonString(txId), jsonString(workspace), jsonString(parentPath)]));
+  }
+
+  /** `raisin.tx.move` — registry method `tx_move`. Returns raw JSON. */
+  export function move(txId: string, workspace: string, nodePath: string, newParentPath: string): string {
+    return call("tx_move", argsOf([jsonString(txId), jsonString(workspace), jsonString(nodePath), jsonString(newParentPath)]));
+  }
+
+  /** `raisin.tx.put` — registry method `tx_put`. Returns raw JSON. */
+  export function put(txId: string, workspace: string, data: string): string {
+    return call("tx_put", argsOf([jsonString(txId), jsonString(workspace), data]));
+  }
+
+  /** `raisin.tx.rollback` — registry method `tx_rollback`. Returns raw JSON. */
+  export function rollback(txId: string): string {
+    return call("tx_rollback", argsOf([jsonString(txId)]));
+  }
+
+  /** `raisin.tx.setActor` — registry method `tx_setActor`. Returns raw JSON. */
+  export function setActor(txId: string, actor: string): string {
+    return call("tx_setActor", argsOf([jsonString(txId), jsonString(actor)]));
+  }
+
+  /** `raisin.tx.setMessage` — registry method `tx_setMessage`. Returns raw JSON. */
+  export function setMessage(txId: string, message: string): string {
+    return call("tx_setMessage", argsOf([jsonString(txId), jsonString(message)]));
+  }
+
+  /** `raisin.tx.update` — registry method `tx_update`. Returns raw JSON. */
+  export function update(txId: string, workspace: string, path: string, data: string): string {
+    return call("tx_update", argsOf([jsonString(txId), jsonString(workspace), jsonString(path), data]));
+  }
+
+  /** `raisin.tx.updateProperty` — registry method `tx_updateProperty`. Returns raw JSON. */
+  export function updateProperty(txId: string, workspace: string, nodePath: string, propertyPath: string, value: string): string {
+    return call("tx_updateProperty", argsOf([jsonString(txId), jsonString(workspace), jsonString(nodePath), jsonString(propertyPath), value]));
+  }
+
+  /** `raisin.tx.upsert` — registry method `tx_upsert`. Returns raw JSON. */
+  export function upsert(txId: string, workspace: string, data: string): string {
+    return call("tx_upsert", argsOf([jsonString(txId), jsonString(workspace), data]));
+  }
+
+  /** `raisin.tx.upsertDeep` — registry method `tx_upsertDeep`. Returns raw JSON. */
+  export function upsertDeep(txId: string, workspace: string, data: string, parentNodeType: string): string {
+    return call("tx_upsertDeep", argsOf([jsonString(txId), jsonString(workspace), data, jsonString(parentNodeType)]));
+  }
+
+}
+

package/assembly/index.ts

@@ -0,0 +1,8 @@
+// Public surface of the RaisinDB AssemblyScript guest SDK.
+//
+// Everything here is a thin layer over `abi.ts`, which owns the canonical-ABI
+// lowering. `generated.ts` carries the typed `raisin.*` wrappers and is emitted
+// from the server's binding registry — do not hand-edit it.
+
+export { call, context, abiVersion, log, HostError, cabi_realloc, run, unknownHandler } from "./abi";
+export * from "./generated";

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@raisindb/function-assemblyscript",
+  "version": "0.1.0",
+  "description": "Guest SDK for writing RaisinDB server functions in AssemblyScript, compiled to a WebAssembly component",
+  "license": "BSL-1.1",
+  "types": "assembly/index.ts",
+  "ascMain": "assembly/index.ts",
+  "files": [
+    "assembly",
+    "wit",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "assemblyscript": ">=0.28"
+  },
+  "devDependencies": {
+    "assemblyscript": "^0.28.20"
+  },
+  "exports": {
+    ".": {
+      "assemblyscript": "./assembly/index.ts",
+      "types": "./assembly/index.ts",
+      "default": "./assembly/index.ts"
+    },
+    "./assembly/*": "./assembly/*"
+  }
+}

package/wit/raisin-function.wit

@@ -0,0 +1,36 @@
+package raisin:function@0.1.0;
+
+/// Host surface for every RaisinDB function component. ONE generic gateway
+/// mirrors `__raisin_call` (QuickJS/Starlark): each raisin.* method has exactly
+/// one implementation, the registry invoker.
+interface host {
+    enum log-level { debug, info, warn, error }
+
+    /// Call a RaisinDB API method by registry `internal_name` ("nodes_get",
+    /// "http_request", "context_get", ...). `args` is a JSON array of positional
+    /// arguments; `null` = absent optional. Ok = `InvokeResult::to_json_string()`.
+    /// Err = human-readable message (unknown method, bad args, API error).
+    call: func(method: string, args: string) -> result<string, string>;
+
+    /// Structured log line -> ExecutionResult.logs + SSE log emitter.
+    log: func(level: log-level, message: string);
+
+    /// Execution context JSON, byte-identical to `raisin.context.get()` in JS/Starlark
+    /// (`FunctionApi::get_context`).
+    context: func() -> string;
+
+    /// Host ABI semver ("0.1.0"); SDKs refuse hosts older than they were generated for.
+    abi-version: func() -> string;
+}
+
+world function {
+    import host;
+
+    /// The single entry point. `name` is the handler selected by the Function
+    /// node's `entry_file` suffix (`main.wasm:on-order` -> "on-order"; a bare
+    /// `main.wasm` -> "default"), so ONE artifact can carry many handlers and
+    /// many Function nodes can share one artifact.
+    /// `input` = JSON-encoded function input. Ok = JSON output. Err = failure message.
+    /// An unknown `name` must return Err listing the names the guest registered.
+    export handler: func(name: string, input: string) -> result<string, string>;
+}