@friggframework/admin-scripts 2.0.0--canary.517.559ad7e.0 → 2.0.0--canary.517.beaf080.0

package/README.md

@@ -228,7 +228,7 @@ Scheduling requires `admin.enableScheduling: true` in the app definition (so the
 
 ## Script chaining
 
-Long or fan-out work can enqueue follow-up scripts. Continuations are tracked with `parentExecutionId` so you can trace the lineage:
+A script can enqueue follow-up scripts via `queueScript()` / `queueScriptBatch()`. Each continuation runs **asynchronously** in the executor Lambda (trigger `QUEUE`) with its `parentExecutionId` set to the queuing execution, so you can trace the lineage (and query children by `parentExecutionId`).
 
 ```javascript
 async execute(params) {
@@ -240,6 +240,24 @@ async execute(params) {
 }
 ```
 
+### When to reach for it
+
+Chaining is the escape hatch for work that doesn't fit a single execution. Use it to:
+
+-   **Beat the timeouts** — sync runs in the API Lambda (≈30s); async in the executor (15-min max). Split bigger jobs into children, each with its own 15-min budget.
+-   **Page / resume** — process one page, queue a continuation with the next cursor; a job of any length never hits the wall.
+-   **Fan out** — one child per item/batch runs concurrently (bounded by the queue) instead of one script grinding serially.
+-   **Isolate failures** — one bad item fails only that child's execution; siblings continue.
+-   **Stage pipelines** — script A finishes and queues script B with its output, each stage independently retried/timed.
+
+For small, bounded, fast work — or when you need the result in the response — just use a single sync/async execution instead.
+
+### Caveats
+
+-   **Fire-and-forget** — you don't get a child's result back; correlate via `parentExecutionId`.
+-   **At-least-once delivery** — a child may run more than once (SQS redrive on crash). **Make child scripts idempotent.**
+-   **No depth guard** — a script that queues itself fans out unbounded. Keep continuation targets terminal, or bound the chain yourself.
+
 ---
 
 ## Execution modes & reliability

package/package.json

@@ -1,19 +1,19 @@
 {
     "name": "@friggframework/admin-scripts",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.517.559ad7e.0",
+    "version": "2.0.0--canary.517.beaf080.0",
     "description": "Admin Script Runner for Frigg - Execute maintenance and operational scripts in hosted environments",
     "dependencies": {
         "@aws-sdk/client-scheduler": "^3.588.0",
-        "@friggframework/core": "2.0.0--canary.517.559ad7e.0",
+        "@friggframework/core": "2.0.0--canary.517.beaf080.0",
         "@hapi/boom": "^10.0.1",
         "express": "^4.18.2",
         "serverless-http": "^3.2.0"
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.517.559ad7e.0",
-        "@friggframework/prettier-config": "2.0.0--canary.517.559ad7e.0",
-        "@friggframework/test": "2.0.0--canary.517.559ad7e.0",
+        "@friggframework/eslint-config": "2.0.0--canary.517.beaf080.0",
+        "@friggframework/prettier-config": "2.0.0--canary.517.beaf080.0",
+        "@friggframework/test": "2.0.0--canary.517.beaf080.0",
         "eslint": "^8.22.0",
         "jest": "^29.7.0",
         "prettier": "^2.7.1",
@@ -44,5 +44,5 @@
         "maintenance",
         "operations"
     ],
-    "gitHead": "559ad7ed62bf320273a70e2bb9e30ec67a026355"
+    "gitHead": "beaf080b1337695f52525105e87e02c38d29b490"
 }

package/src/application/admin-script-context.js

@@ -57,6 +57,24 @@ class AdminScriptContext {
 
     // ==================== QUEUE OPERATIONS ====================
 
+    /**
+     * Enqueue a follow-up script as an async continuation of this execution.
+     *
+     * Fire-and-forget: the child runs later in the executor Lambda (trigger
+     * `QUEUE`) with its `parentExecutionId` set to this execution — you do NOT
+     * get the child's result back here. Use it to split work that won't fit one
+     * execution (paging past the 15-min executor timeout, per-item fan-out,
+     * multi-stage pipelines).
+     *
+     * Caveats: delivery is at-least-once, so child scripts must be idempotent;
+     * and there is no recursion/depth guard, so a script that queues itself
+     * fans out unbounded — keep continuation targets terminal or bound the chain
+     * yourself.
+     *
+     * @param {string} scriptName - Registered name of the script to enqueue
+     * @param {Object} [params={}] - Params passed to the child's execute()
+     * @throws {Error} if ADMIN_SCRIPT_QUEUE_URL is not configured
+     */
     async queueScript(scriptName, params = {}) {
         const queueUrl = process.env.ADMIN_SCRIPT_QUEUE_URL;
         if (!queueUrl) {
@@ -78,6 +96,14 @@ class AdminScriptContext {
         this.log('info', `Queued continuation for ${scriptName}`, { params });
     }
 
+    /**
+     * Enqueue many follow-up scripts at once (batched to SQS). Same semantics
+     * and caveats as {@link queueScript} — each child runs async with this
+     * execution as its parent; make children idempotent and keep them terminal.
+     *
+     * @param {Array<{scriptName: string, params?: Object}>} entries - Scripts to enqueue
+     * @throws {Error} if ADMIN_SCRIPT_QUEUE_URL is not configured
+     */
     async queueScriptBatch(entries) {
         const queueUrl = process.env.ADMIN_SCRIPT_QUEUE_URL;
         if (!queueUrl) {