Track HiveGrid Cloud planning reference

hivegrid-cloud/packages/plugin-sdk/examples/async-task/handler.ts

@@ -0,0 +1,44 @@
+/**
+ * Async-task example — Phase 06 #23.
+ *
+ * Long-running side effects should not run inside the plugin invocation
+ * (the sandbox has a fuel ceiling and the hook fan-out is blocked
+ * while a handler runs). Instead, the plugin records an audit event
+ * and returns immediately; a host worker picks up the event from the
+ * outbox and does the heavy lifting outside the sandbox.
+ *
+ * The plugin never blocks waiting on the worker — that is the whole
+ * point of the pattern. If the host wants a callback, it emits a new
+ * hook event when the worker is done; the plugin can subscribe to
+ * that too.
+ */
+import { defineHook, type PluginHookEntityPayload } from "../../src/index.js";
+
+export const handleEntityUpdated = defineHook<PluginHookEntityPayload, { enqueued: boolean }>(
+  async (input, ctx) => {
+    ctx.log.info(
+      {
+        tenantId: input.tenantId,
+        entity: input.entityType,
+        changedFieldCount: input.changedFields?.length ?? 0,
+      },
+      "async-task.handleEntityUpdated received update"
+    );
+
+    // Record one structured audit event — the host worker subscribes
+    // to plugin-emitted audit events and runs the actual work. Body
+    // is bounded so we don't accidentally turn the audit log into a
+    // queue (the audit sink rejects payloads above its cap).
+    await ctx.audit.record({
+      action: "async-task.work-requested",
+      target: `${input.entityType}:${input.entityId}`,
+      meta: {
+        tenantId: input.tenantId,
+        changedFieldCount: input.changedFields?.length ?? 0,
+      },
+    });
+
+    ctx.log.info({}, "async-task enqueued work-request, returning fast");
+    return { enqueued: true };
+  }
+);