🦸 SentaiTask 戦隊

Visual orchestration for InterSystems IRIS maintenance tasks

Every task a squad member. Every flow a coordinated attack.

🌌 Motivation

IRIS maintenance jobs such as integrity checks, journal switches, purges and compaction are
usually scheduled one at a time in the Task Manager. Their order, their dependencies and “what
happens if one fails” are kept in someone’s head or in a runbook.

SentaiTask turns that tacit knowledge into a declared, validated, observable flow:

• ✅ Compose a flow as a graph: steps run in parallel waves and fan in at join points.
• ✅ Validate before running: cycles, unknown or unsupported step types, missing parameters,
  missing namespaces, unknown WQM categories, read-only databases.
• ✅ Dispatch and track: every step becomes a platform job with its own GUID, state and
  verbatim failure reason, followed live on the canvas (the API also streams it over
  Server-Sent Events).
• ✅ Stay honest: the product only offers what the target IRIS instance was proven to do (see
  Known limitations).

Like a sentai squad, each step has its own role, and the flow decides when they move together.

🛠️ How It Works

SentaiTask is an ObjectScript backend on top of the IRIS management API (/api/admin), plus a
canvas UI that IRIS serves itself. It does not reimplement the platform’s permissions: every
platform call is made with the operator’s own credential (Constitution III, Delegated
Authorization).

Core pieces

1. Flow model (sentai.model): Flow, Step, Edge, Join, Run, StepRun and LogEntry, persisted
   in IRIS. Edges are acyclic and fan-in joins use ALL_MUST_SUCCEED.
2. Step-type registry (sentai.registry.StepType): a closed, compiled catalog. No code is ever
   taken from input. Each type declares whether it is destructive, pausable and available on the
   target platform.
3. Validator (sentai.validation.FlowValidator): a single gate shared by validate, dispatch
   and schedule, so a flow that fails /validate can never be run.
4. Wave dispatcher (sentai.dispatch.WaveDispatcher): creates the Run and one StepRun per
   step in a single transaction, enqueues eligible steps on the step’s WQM category, starts the
   platform job and follows it to a terminal state.
5. REST API + SSE (sentai.rest.Dispatcher): /csp/sentai/api/v1, with password + JWT
   authentication and no unauthenticated access.
6. Canvas UI (frontend/): SvelteKit + Svelte Flow, compiled to static files in a Node stage
   of the Dockerfile and served by IRIS’s own web server at /csp/sentai/ through
   sentai.web.StaticFiles, behind the IRIS password (no unauthenticated web app). No Node
   process runs in the shipped container; the page talks only to the two APIs above.

Architecture overview

┌─────────────────────────────────────────────────────────────┐
│                 Operator (curl / canvas UI)                 │
└─────────────────────────┬───────────────────────────────────┘
                          │ Bearer token from /api/admin/login
                          ▼
┌─────────────────────────────────────────────────────────────┐
│            REST  /csp/sentai/api/v1  (sentai.rest)          │
│   flows · validate · dispatch · runs · events (SSE) · wqm   │
└──────────┬──────────────────────────────┬───────────────────┘
           │                              │
           ▼                              ▼
┌──────────────────────┐      ┌───────────────────────────────┐
│   FlowValidator      │◀─────│   WaveDispatcher              │
│   one gate for       │      │   Run + StepRuns (1 tx)       │
│   validate/dispatch/ │      │   waves → %SYSTEM.WorkMgr     │
│   schedule           │      │   (per WQM category)          │
└──────────┬───────────┘      └──────────────┬────────────────┘
           │ categories                      │ start / poll / pause
           ▼                                 ▼
┌─────────────────────────────────────────────────────────────┐
│          IRIS management API  /api/admin  (platform)        │
│   wqm-categories · database-dir/integrity-check ·           │
│   async-result                                              │
└─────────────────────────────────────────────────────────────┘

📋 Prerequisites

• Git
• Docker Desktop with Docker Compose
• InterSystems IRIS 2026.2. The container image built by this repo is the verified target.

🛠️ Installation

Docker

git clone https://github.com/musketeers-br/sentai-task.git
cd sentai-task
docker-compose up -d --build

The build compiles the canvas, loads the sentai-task module and registers the REST application
/csp/sentai/api/v1 on http://localhost:52773. When the container is up, open

http://localhost:52773/csp/sentai/

Sign in to the canvas with your IRIS user (_SYSTEM / SYS on this dev image). That sign-in
exchanges the password for short-lived API tokens, which stay in memory only; the password is
never stored.

What is public and what is not: the page itself (HTML, JS, CSS) is served without
authentication by sentai.web.StaticFiles, which only reads the canvas build and holds no
data. Its code lives in a small database, SENTAIWEB, and the app’s role SentaiWebPage only
lets the anonymous request enter the namespace (read on its default globals database). Every
flow and run goes through the REST API, which always requires a token.

IPM

In an IRIS instance with the IPM client:

USER>zpm "install sentai-task"

💡 How to Use

On the canvas

1. Compose. Drag Integrity check from the palette onto the canvas (the other step types are
   listed but marked not supported in v1, see Known limitations).
   Drag from a step’s right handle to another step’s left handle to connect them; edges that would
   create a cycle are refused as you draw. Several edges into one step meet at a single diamond:
   that step waits for all of them. Click a step to edit it in the inspector, then Save flow.
2. Validate flow. Errors (unknown namespace or category, unsupported type, missing parameter)
   appear on the affected node and block running; warnings, such as a read-only database, are
   shown but do not block.
3. Run now. You are asked for your password once: the run gets its own sign-in and renews its
   credential by itself for as long as it runs. The password is not kept.
4. Watch. The live-run view shows each step’s state, elapsed time and, if it fails, the
   platform’s own failure message. Cancel one step without touching the others, or Cancel wave
   for the whole run.

The Dark / Light switch in the top bar changes theme on every screen.

With the API

1. Get a token

The API uses the same 60-second JWT as the IRIS management API:

TOKEN=$(curl -s -X POST -u _SYSTEM:SYS http://localhost:52773/api/admin/login | jq -r .access_token)

2. Compose a flow

Two integrity checks run in parallel and fan in to a third:

curl -s -X POST http://localhost:52773/csp/sentai/api/v1/flows \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "schemaVersion": 1,
    "name": "nightly-checks",
    "defaultCategory": "Default",
    "steps": [
      {"id": "01", "type": "integrity-check", "taskName": "IC USER",    "namespace": "USER",    "wqmCategory": "Default"},
      {"id": "02", "type": "integrity-check", "taskName": "IC IRISAPP", "namespace": "IRISAPP", "wqmCategory": "Default"},
      {"id": "03", "type": "integrity-check", "taskName": "IC %SYS",    "namespace": "%SYS",    "wqmCategory": "Default"}
    ],
    "edges": [ {"source": "01", "target": "03"}, {"source": "02", "target": "03"} ],
    "joins": [ {"target": "03", "policy": "ALL_MUST_SUCCEED"} ]
  }'

3. Validate, dispatch and watch

curl -s -X POST http://localhost:52773/csp/sentai/api/v1/flows//validate  -H "Authorization: Bearer $TOKEN"
# {"errors":[],"warnings":[]}
curl -s -X POST http://localhost:52773/csp/sentai/api/v1/flows//dispatch  -H "Authorization: Bearer $TOKEN" 

-H "Content-Type: application/json" -d '{"confirmations": []}'
202 {"guid": "", "state": "running", ...}
curl -N http://localhost:52773/csp/sentai/api/v1/runs//events -H "Authorization: Bearer $TOKEN"
event: step-state-changed ... event: run-terminal

Steps 01 and 02 start together. Step 03 stays queued until both complete.

A run dispatched like this keeps the 60-second token it was given. To let it run longer, sign in
separately for the run and add that sign-in’s refresh token to the body,
"runCredential": {"refreshToken": "…"}, while sending its access token in Authorization. The
run then renews its own credential and erases it when it ends. The canvas does this for you.

API at a glance

Validation errors come back as {"errors": [{"stepId", "code", "message"}], "warnings": [...]},
with codes such as CYCLE_DETECTED, STEP_TYPE_NOT_SUPPORTED_ON_TARGET and CATEGORY_NOT_FOUND.

⚠️ Known limitations (v1)

SentaiTask v1 only promises what was proven on IRIS 2026.2 (spec 004-backend-hardening):

• Only integrity-check runs. The other six step types (compact-globals,
  defragment-globals, switch-journal, purge-audit-records, purge-task-history, custom)
  are still listed in GET /catalog/step-types with available: false, and saved flows that use
  them still load. Validate, dispatch, schedule and rerun refuse them with
  STEP_TYPE_NOT_SUPPORTED_ON_TARGET.
• Scheduling is not operational. /schedule validates the flow and registers a native task,
  but scheduled runs cannot authenticate to the platform in v1 and are not a supported execution
  path. Use manual dispatch.
• Run credential. A dispatched run calls the platform with an access token that expires 60 s
  after it was issued, and refreshing a token revokes the previous one. The canvas therefore asks
  for the password at Run now, dispatches under a separate sign-in, and passes that sign-in’s
  refresh token (runCredential), with which the run renews its own credential until it ends —
  then both are erased. A dispatch without runCredential (e.g. plain curl) keeps the 60 s
  limit: later platform calls fail with 401, stored verbatim as the step’s failure reason.
• Step parameters are not forwarded. The platform start request carries no parameters, so
  databaseDirectory and similar fields do not choose what the platform operates on.
• Flows must name an existing WQM category. Validation refuses an unknown category with
  CATEGORY_NOT_FOUND. The default for new flows, SENTAI.DEFAULT, does not exist on a stock
  instance, so set a category such as Default.
• No v1-available step type is destructive or pausable, so typed confirmation and pause are
  implemented but cannot be reached.

🧪 Running the tests

docker exec -it sentai-task-iris-1 iris session iris -U IRISAPP

IRISAPP>zpm "load /home/irisowner/dev"
IRISAPP>zpm "test sentai-task -only"

The suite (sentai.unittest.*, 115 methods) runs against a test double of the management API, so
it never starts real platform jobs through the admin API.

The canvas has unit tests and end-to-end acceptance tests (these need Node 20+ on your machine and
the container running):

cd frontend
npm ci
npm test                    # unit tests (vitest)
npx playwright install chromium
npm run test:e2e            # acceptance tests against http://localhost:52773

The acceptance tests drive real runs, so they take about six minutes; screenshots and captures
land in https://github.com/musketeers-br/sentai-task/blob/master/specs/002-canvas-ui/evidence/.

🗂️ Project Structure

sentai-task/
├── src/sentai/
│   ├── model/          # Flow, Step, Edge, Join, Run, StepRun, Category, LogEntry
│   ├── registry/       # StepType: closed catalog (destructive / pausable / available)
│   ├── validation/     # FlowValidator: the single gate
│   ├── dispatch/       # WaveDispatcher, AdminApiClient, ScheduledFlowTask
│   ├── wqm/            # CategoryService: WQM read/write passthrough
│   ├── catalog/        # TaskService: native Task Manager catalog
│   └── rest/           # Dispatcher: REST API + SSE
├── tests/sentai/unittest/   # %UnitTest suites + AdminApiDouble
├── frontend/           # Canvas UI: SvelteKit + Svelte Flow, built to static files
├── design/             # Canvas UI prototypes (spec 002)
├── specs/              # Spec-driven history: 001 contract spike → 004 hardening
├── scripts/sanitation/ # Reviewed cleanup of historical test residue
├── module.xml
└── docker-compose.yml

📊 Roadmap

✅ Done

• 001: Contract spike against the real IRIS management API (compatibility statement)
• 003: ObjectScript backend: persistence, validation, wave dispatch, SSE tracking
• 004: Hardening. The product only promises what IRIS 2026.2 proved.
• 002: Canvas UI: compose, validate, schedule, run and watch flows, in dark and light
• Runs renew their own credential when dispatched with runCredential (runs > 60 s work)

🚧 Next

• WQM category screen, task catalog and run history in the canvas (the API already has them)
• A credential for scheduled runs (unblocks scheduling)
• Prove and enable the remaining step types, one at a time

🎖️ Credits

SentaiTask is developed with 💜 by the Musketeers Team:

• José Roberto Pereira
• Henry Pereira
• Henrique Dias

📄 License

This project is licensed under the MIT License.

🎬 Bonus: Musketeers Sentai

When the flow validates clean, the squad suits up.