@intentius/chant-lexicon-temporal 0.1.5

package/dist/integrity.json

@@ -0,0 +1,15 @@
+{
+  "algorithm": "sha256",
+  "artifacts": {
+    "manifest.json": "6e636e68d039c23e7a244602a31d0cd38192b7cbe719aabff99eb7d485c71291",
+    "meta.json": "c77a3c415993bed3865e07fa6db4fb7b9e87de0afa8d8675f64eadf50f914077",
+    "types/index.d.ts": "5216f5256321f084a7c8211ef66ab599f621c74751cc3485cfc2a62502b81e2f",
+    "rules/tmp001.ts": "689222211a93716a7e4432f6dd6a2a2ab54020b232049fb602893872585f9978",
+    "rules/tmp002.ts": "a227dc8c9aae16bbb468664a35a199c0880827b15075227c8e26a8c5fe2eff30",
+    "rules/tmp010-cron-syntax.ts": "47db78e7595bcd24a9a735dfd738e11b2d3d9465e317ae836fb3da8ff74cee63",
+    "rules/tmp011-namespace-reference.ts": "221c7832ab3012c1cf1e3a9f4a7f6fa8958b85b5fc0c75ab9673c920cbc97833",
+    "skills/chant-temporal.md": "ff929983b33bb420c49ab61851f3799c5610256cb972d6c584792bb98b0cfb22",
+    "skills/chant-temporal-ops.md": "7e83bc3e6e63af4ab14b8dc07aa00132d51991cf35b1bca29560d48934bff6dc"
+  },
+  "composite": "ead26ea60623f339408c9a74f60a55a506a2d5b0f6fafc041eefc2ca92bb5b04"
+}

package/dist/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "temporal",
+  "version": "0.1.5",
+  "chantVersion": ">=0.1.0",
+  "namespace": "Temporal",
+  "intrinsics": [],
+  "pseudoParameters": {}
+}

package/dist/meta.json

@@ -0,0 +1,26 @@
+{
+  "TemporalServer": {
+    "resourceType": "Temporal::Server",
+    "kind": "resource",
+    "lexicon": "temporal",
+    "description": "Temporal server deployment — emits docker-compose.yml and Helm values"
+  },
+  "TemporalNamespace": {
+    "resourceType": "Temporal::Namespace",
+    "kind": "resource",
+    "lexicon": "temporal",
+    "description": "Temporal namespace — emits namespace create command in temporal-setup.sh"
+  },
+  "SearchAttribute": {
+    "resourceType": "Temporal::SearchAttribute",
+    "kind": "resource",
+    "lexicon": "temporal",
+    "description": "Temporal search attribute — emits search-attribute create command in temporal-setup.sh"
+  },
+  "TemporalSchedule": {
+    "resourceType": "Temporal::Schedule",
+    "kind": "resource",
+    "lexicon": "temporal",
+    "description": "Temporal schedule — emits SDK schedule creation TypeScript to schedules/<id>.ts"
+  }
+}

package/dist/rules/tmp001.ts

@@ -0,0 +1,53 @@
+/**
+ * TMP001: TemporalNamespace retention too short
+ *
+ * Workflow history older than the retention period is permanently deleted.
+ * Retentions shorter than 3 days leave very little time for debugging
+ * failures or running ad-hoc queries against closed workflow executions.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+
+/** Parse a retention string like "1d", "12h", "3d" → total hours. Returns NaN on unrecognised format. */
+function retentionHours(retention: string): number {
+  const days = /^(\d+)d$/i.exec(retention);
+  if (days) return Number(days[1]) * 24;
+  const hours = /^(\d+)h$/i.exec(retention);
+  if (hours) return Number(hours[1]);
+  return NaN;
+}
+
+export const tmp001: LintRule = {
+  id: "TMP001",
+  severity: "error",
+  category: "correctness",
+  description: "TemporalNamespace retention should be at least 3 days to preserve workflow history for debugging",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+
+    for (const [name, entity] of context.entities) {
+      const et = (entity as Record<string, unknown>).entityType as string;
+      if (et !== "Temporal::Namespace") continue;
+
+      const props = (entity as { props?: Record<string, unknown> }).props ?? {};
+      const retention = props.retention as string | undefined;
+      if (!retention) continue; // default "7d" — not an error
+
+      const hours = retentionHours(retention);
+      if (isNaN(hours)) continue; // unrecognised format — skip
+
+      if (hours < 72) {
+        diagnostics.push({
+          ruleId: "TMP001",
+          severity: "error",
+          message: `Namespace "${name}" has retention "${retention}" — minimum recommended is 3d (72h) to preserve workflow history`,
+          entity: name,
+          fix: 'Set retention to at least "3d" — e.g. retention: "7d"',
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tmp002.ts

@@ -0,0 +1,45 @@
+/**
+ * TMP002: TemporalSchedule AllowAll overlap without explanatory note
+ *
+ * AllowAll allows any number of concurrent schedule runs. This is safe for
+ * idempotent, read-only workflows, but can cause resource exhaustion or
+ * duplicate side-effects if not explicitly intended. Requiring a note forces
+ * the author to document the intent.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+
+export const tmp002: LintRule = {
+  id: "TMP002",
+  severity: "warning",
+  category: "best-practices",
+  description: "TemporalSchedule with overlap AllowAll should include state.note explaining the intent",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+
+    for (const [name, entity] of context.entities) {
+      const et = (entity as Record<string, unknown>).entityType as string;
+      if (et !== "Temporal::Schedule") continue;
+
+      const props = (entity as { props?: Record<string, unknown> }).props ?? {};
+      const policies = props.policies as Record<string, unknown> | undefined;
+      if (policies?.overlap !== "AllowAll") continue;
+
+      const state = props.state as Record<string, unknown> | undefined;
+      const note = state?.note as string | undefined;
+
+      if (!note || note.trim() === "") {
+        diagnostics.push({
+          ruleId: "TMP002",
+          severity: "warning",
+          message: `Schedule "${name}" uses overlap "AllowAll" — add state.note explaining why concurrent runs are safe`,
+          entity: name,
+          fix: 'Add state: { note: "Workflow is idempotent — concurrent runs are safe" }',
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tmp010-cron-syntax.ts

@@ -0,0 +1,64 @@
+/**
+ * TMP010: TemporalSchedule cron expression syntax
+ *
+ * Validates that cron expressions in TemporalSchedule.spec.cronExpressions
+ * are valid 5- or 6-field cron syntax. Malformed crons are silently ignored
+ * by Temporal's scheduler, leading to schedules that never fire.
+ *
+ * This is a pre-submission guard — final validation is Temporal's own parser.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+
+/** Very permissive cron field pattern — catches obvious syntax errors. */
+const CRON_FIELD = /^[0-9*,/\-?LW#]+$/;
+
+function isValidCronExpression(expr: string): boolean {
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length < 5 || fields.length > 6) return false;
+  return fields.every((f) => CRON_FIELD.test(f));
+}
+
+export const tmp010: PostSynthCheck = {
+  id: "TMP010",
+  description: "TemporalSchedule cron expressions must be valid 5- or 6-field cron syntax",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [lexicon, output] of ctx.outputs) {
+      if (lexicon !== "temporal") continue;
+
+      // Schedules emit individual TypeScript files — check the schedules/ files.
+      const files =
+        typeof output === "string"
+          ? new Map<string, string>()
+          : (output as { primary: string; files?: Record<string, string> }).files
+            ? new Map(Object.entries((output as { files: Record<string, string> }).files))
+            : new Map<string, string>();
+
+      for (const [filename, content] of files) {
+        if (!filename.startsWith("schedules/")) continue;
+
+        // Extract cron expressions from the generated TypeScript:
+        // cronExpressions: ["0 3 * * *"]
+        const cronMatches = [...content.matchAll(/cronExpressions:\s*\[([^\]]+)\]/g)];
+        for (const match of cronMatches) {
+          const exprs = [...match[1].matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+          for (const expr of exprs) {
+            if (!isValidCronExpression(expr)) {
+              diagnostics.push({
+                checkId: "TMP010",
+                severity: "warning",
+                message: `${filename}: cron expression "${expr}" does not look like valid 5- or 6-field cron syntax`,
+                lexicon: "temporal",
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tmp011-namespace-reference.ts

@@ -0,0 +1,49 @@
+/**
+ * TMP011: SearchAttribute references an undeclared namespace
+ *
+ * If SearchAttribute.namespace is set to a value X, there must be a
+ * TemporalNamespace entity with name === X in the project. A missing
+ * namespace means the search attribute create command will fail at runtime.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+
+export const tmp011: PostSynthCheck = {
+  id: "TMP011",
+  description: "SearchAttribute.namespace must reference a declared TemporalNamespace entity",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    // Collect declared namespace names
+    const declaredNamespaces = new Set<string>();
+    for (const [, entity] of ctx.entities) {
+      const et = (entity as Record<string, unknown>).entityType as string;
+      if (et !== "Temporal::Namespace") continue;
+      const props = (entity as { props?: Record<string, unknown> }).props ?? {};
+      const name = props.name as string | undefined;
+      if (name) declaredNamespaces.add(name);
+    }
+
+    // Check each SearchAttribute that specifies a namespace
+    for (const [entityKey, entity] of ctx.entities) {
+      const et = (entity as Record<string, unknown>).entityType as string;
+      if (et !== "Temporal::SearchAttribute") continue;
+
+      const props = (entity as { props?: Record<string, unknown> }).props ?? {};
+      const ns = props.namespace as string | undefined;
+      if (!ns) continue; // no namespace specified — applies globally, OK
+
+      if (!declaredNamespaces.has(ns)) {
+        diagnostics.push({
+          checkId: "TMP011",
+          severity: "error",
+          message: `SearchAttribute "${entityKey}" references namespace "${ns}" which is not declared — add a TemporalNamespace with name "${ns}"`,
+          lexicon: "temporal",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/skills/chant-temporal-ops.md

@@ -0,0 +1,184 @@
+---
+skill: chant-temporal-ops
+description: Signal workflows, diagnose stuck activities, reset checkpoints, and cancel runs via the Temporal CLI and chant run
+user-invocable: true
+---
+
+# Temporal Operations Playbook
+
+## Signal a gate (unblock a paused workflow)
+
+Workflows that use `setHandler` on a signal pause at gate activities waiting for a named signal. The `chant run signal` command (available in issue #8) forwards signals to the running workflow.
+
+```bash
+# Via chant CLI (requires chant run — issue #8)
+chant run signal <op-name> dnsConfigured
+
+# Directly via temporal CLI
+temporal workflow signal \
+  --workflow-id <workflow-id> \
+  --name dnsConfigured \
+  --namespace <namespace>
+```
+
+List pending signals by querying the workflow:
+
+```bash
+temporal workflow query \
+  --workflow-id <workflow-id> \
+  --type currentPhase \
+  --namespace <namespace>
+```
+
+## Check run status
+
+```bash
+# Summary view
+temporal workflow describe --workflow-id <id> --namespace <ns>
+
+# Full event history
+temporal workflow show --workflow-id <id> --namespace <ns>
+
+# Filter by search attribute (requires registered custom attributes)
+temporal workflow list \
+  --namespace <ns> \
+  --query 'GcpProject = "my-project"'
+```
+
+## Diagnose a stuck activity
+
+Activities can be stuck for three distinct reasons:
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Activity never started | `scheduleToStartTimeout` exceeded — no available workers | Start the worker: `chant run <op>` |
+| Activity started but no heartbeats | `heartbeatTimeout` exceeded — worker crashed mid-activity | Bounce the worker; Temporal auto-retries |
+| Activity running but slow | Normal — long-running activities with heartbeats | Wait, or check heartbeat details |
+
+### View activity timeout details
+
+```bash
+temporal workflow show --workflow-id <id> --namespace <ns> | grep -A5 "ActivityTaskScheduled"
+```
+
+### Check worker connectivity
+
+```bash
+# See which task queues have pollers
+temporal task-queue describe --task-queue <queue> --namespace <ns>
+```
+
+A task queue with `pollerCount: 0` means no workers are running.
+
+## Reset a workflow to a previous checkpoint
+
+Use `workflow reset` to replay a workflow from a specific event, skipping failed activities:
+
+```bash
+# Reset to just before the most recent failure
+temporal workflow reset \
+  --workflow-id <id> \
+  --namespace <ns> \
+  --event-id <N> \
+  --reason "Retrying after infra fix"
+```
+
+Find the event ID to reset to:
+
+```bash
+# List events — find the last successful ActivityTaskCompleted before the failure
+temporal workflow show --workflow-id <id> --namespace <ns> | grep -n "ActivityTask"
+```
+
+Reset to the beginning of a named phase (requires workflow to record phase transitions as signals or markers):
+
+```bash
+temporal workflow reset \
+  --workflow-id <id> \
+  --namespace <ns> \
+  --reapply-type None \
+  --type LastWorkflowTask
+```
+
+## Cancel a stuck or unwanted run
+
+```bash
+# Graceful cancel — workflow receives CancellationError and can clean up
+temporal workflow cancel \
+  --workflow-id <id> \
+  --namespace <ns>
+
+# Forceful terminate — immediate stop, no cleanup
+temporal workflow terminate \
+  --workflow-id <id> \
+  --namespace <ns> \
+  --reason "Terminated by operator"
+```
+
+## Pause and resume a schedule
+
+```bash
+# Pause
+temporal schedule pause \
+  --schedule-id <id> \
+  --namespace <ns> \
+  --note "Paused for maintenance"
+
+# Resume
+temporal schedule unpause \
+  --schedule-id <id> \
+  --namespace <ns>
+
+# Trigger immediately (ignores spec)
+temporal schedule trigger \
+  --schedule-id <id> \
+  --namespace <ns>
+```
+
+## Inspect workflow history for debugging
+
+```bash
+# Show all events in JSON (machine-readable)
+temporal workflow show \
+  --workflow-id <id> \
+  --namespace <ns> \
+  --output json
+
+# Filter to activity failures only
+temporal workflow show \
+  --workflow-id <id> \
+  --namespace <ns> \
+  --output json | jq '.[] | select(.eventType == "ActivityTaskFailed")'
+```
+
+## Common failure patterns
+
+### "no workers polling" after `chant run`
+
+The worker started but cannot connect. Check:
+1. `TEMPORAL_ADDRESS` matches the server address
+2. `TEMPORAL_NAMESPACE` matches the namespace the workflow was started in
+3. TLS and API key config match (`tls: true` + `apiKey` for Temporal Cloud)
+
+### Activity retrying indefinitely
+
+Default retry policy has `maximumAttempts: 0` (unlimited). If an activity is retrying unexpectedly:
+
+```bash
+# Check the current attempt count and last failure
+temporal workflow show --workflow-id <id> --namespace <ns> | grep "attempt\|failure"
+```
+
+Add `maximumAttempts` to the activity's retry policy in the workflow code, or cancel the run.
+
+### "workflow execution already started" on re-run
+
+`chant run` uses deterministic workflow IDs (e.g. `crdb-deploy-{project}`). If a previous run is still open:
+
+```bash
+# Check if it's still running
+temporal workflow describe --workflow-id <id> --namespace <ns> | grep "status"
+
+# If stuck, terminate it first
+temporal workflow terminate --workflow-id <id> --namespace <ns> --reason "Restarting"
+```

package/dist/skills/chant-temporal.md

@@ -0,0 +1,201 @@
+---
+skill: chant-temporal
+description: Build and manage Temporal server deployment, namespace provisioning, and schedule registration from a chant project
+user-invocable: true
+---
+
+# Temporal Operational Playbook
+
+## How chant and Temporal relate
+
+chant is a **synthesis compiler** — it compiles TypeScript resource declarations into deployment artifacts. `chant build` does not start Temporal or register anything; synthesis is pure and deterministic. Your job as an agent is to bridge synthesis and deployment:
+
+- Use **chant** for: build, lint, diff (local config comparison)
+- Use **docker compose / kubectl / temporal CLI** for: starting the server, applying configs, and all runtime operations
+
+The source of truth for Temporal configuration is the TypeScript in `src/`. The generated artifacts in `dist/` are intermediate outputs.
+
+## Resources and their outputs
+
+| Resource | Emits |
+|---|---|
+| `TemporalServer` | `docker-compose.yml` (primary) + `temporal-helm-values.yaml` |
+| `TemporalNamespace` | `temporal-setup.sh` (namespace create commands) |
+| `SearchAttribute` | `temporal-setup.sh` (search-attribute create commands) |
+| `TemporalSchedule` | `schedules/<id>.ts` (SDK schedule creation script) |
+
+## Build and validate
+
+### Build the project
+
+```bash
+chant build src/ --output dist/
+```
+
+Options:
+- `--watch` — rebuild on source changes
+- `--format json` — not applicable (Temporal outputs are YAML/shell/TypeScript)
+
+### Lint the source
+
+```bash
+chant lint src/
+```
+
+## Start the Temporal server
+
+### Local dev (generated docker-compose.yml)
+
+```bash
+# Start the dev server
+docker compose up -d
+
+# Verify it's running
+temporal operator cluster health
+```
+
+The dev server runs as a single container (`temporal server start-dev`). The Web UI is available at `http://localhost:8080`.
+
+### Temporal Cloud
+
+No server to start. Configure your worker profile in `chant.config.ts`:
+
+```ts
+import type { TemporalChantConfig } from "@intentius/chant-lexicon-temporal";
+
+export default {
+  lexicons: ["temporal"],
+  temporal: {
+    profiles: {
+      cloud: {
+        address: "myns.a2dd6.tmprl.cloud:7233",
+        namespace: "myns.a2dd6",
+        taskQueue: "my-deploy",
+        tls: true,
+        apiKey: { env: "TEMPORAL_API_KEY" },
+      },
+    },
+    defaultProfile: "cloud",
+  } satisfies TemporalChantConfig,
+};
+```
+
+## Provision namespaces and search attributes
+
+After the server is ready, run the generated setup script:
+
+```bash
+bash dist/temporal-setup.sh
+```
+
+This creates namespaces and registers search attributes using the `temporal` CLI. The `TEMPORAL_ADDRESS` env var overrides the default `localhost:7233`:
+
+```bash
+TEMPORAL_ADDRESS=myns.a2dd6.tmprl.cloud:7233 bash dist/temporal-setup.sh
+```
+
+Verify:
+
+```bash
+temporal operator namespace describe --namespace default
+temporal operator search-attribute list --namespace default
+```
+
+## Deploy with Helm
+
+```bash
+helm repo add temporal https://go.temporal.io/server/helm-charts
+helm repo update
+helm install temporal temporal/temporal -f dist/temporal-helm-values.yaml
+```
+
+Wait for all pods:
+
+```bash
+kubectl get pods -l app.kubernetes.io/name=temporal -w
+```
+
+## Register schedules
+
+Each `TemporalSchedule` resource generates a standalone TypeScript runner:
+
+```bash
+# Set connection env vars
+export TEMPORAL_ADDRESS=localhost:7233
+export TEMPORAL_NAMESPACE=default
+
+# Run the generated schedule creation script
+npx tsx dist/schedules/daily-backup.ts
+```
+
+Verify the schedule was created:
+
+```bash
+temporal schedule list --namespace default
+temporal schedule describe --schedule-id daily-backup --namespace default
+```
+
+## Key resource types
+
+| Resource | Purpose |
+|---|---|
+| `TemporalServer` | Server deployment config (dev vs full mode) |
+| `TemporalNamespace` | Namespace with retention policy |
+| `SearchAttribute` | Custom workflow search field |
+| `TemporalSchedule` | Recurring workflow trigger |
+
+## Common patterns
+
+### Minimal local dev stack
+
+```ts
+import { TemporalServer, TemporalNamespace } from "@intentius/chant-lexicon-temporal";
+
+export const server = new TemporalServer({ mode: "dev" });
+export const ns = new TemporalNamespace({ name: "default", retention: "7d" });
+```
+
+### Production namespace with search attributes
+
+```ts
+import { TemporalNamespace, SearchAttribute } from "@intentius/chant-lexicon-temporal";
+
+export const ns = new TemporalNamespace({
+  name: "prod-deploy",
+  retention: "30d",
+  description: "Production deployment workflows",
+});
+
+export const gcpProject = new SearchAttribute({
+  name: "GcpProject",
+  type: "Text",
+  namespace: "prod-deploy",
+});
+
+export const environment = new SearchAttribute({
+  name: "Environment",
+  type: "Keyword",
+  namespace: "prod-deploy",
+});
+```
+
+### Recurring backup schedule
+
+```ts
+import { TemporalSchedule } from "@intentius/chant-lexicon-temporal";
+
+export const backupSchedule = new TemporalSchedule({
+  scheduleId: "daily-backup",
+  spec: {
+    cronExpressions: ["0 3 * * *"],
+  },
+  action: {
+    workflowType: "backupWorkflow",
+    taskQueue: "backup-queue",
+  },
+  policies: {
+    overlap: "Skip",
+    pauseOnFailure: true,
+  },
+});
+```

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+// Types for @intentius/chant-lexicon-temporal are declared in src/resources.ts.
+// They are available via the package's main export: import { ... } from "@intentius/chant-lexicon-temporal";
+export {};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@intentius/chant-lexicon-temporal",
+  "version": "0.1.5",
+  "description": "Temporal lexicon for chant — server deployment, namespaces, search attributes, and schedules",
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts",
+    "./manifest": "./dist/manifest.json",
+    "./meta": "./dist/meta.json",
+    "./types": "./dist/types/index.d.ts"
+  },
+  "scripts": {
+    "generate": "tsx src/codegen/generate-cli.ts",
+    "bundle": "tsx src/codegen/package-cli.ts",
+    "validate": "tsx src/validate-cli.ts",
+    "docs": "tsx src/codegen/docs-cli.ts",
+    "prepack": "npm run generate && npm run bundle && npm run validate"
+  },
+  "peerDependencies": {
+    "@intentius/chant": "^0.1.0"
+  },
+  "devDependencies": {
+    "@intentius/chant": "*",
+    "typescript": "^5.9.3"
+  }
+}