@sequenceholdings/studio-cli 0.1.13 → 0.1.21

package/dist/pipeline/lifecycle.js

@@ -0,0 +1,348 @@
+/**
+ * Deploy lifecycle verbs for `seq-studio pipeline plan|deploy|promote|rollback`
+ * (SEQ-2450). Wraps the /api/data-pipelines plan/deploy APIs.
+ */
+import { getAccessToken, NotLoggedInError } from '../auth.js';
+import { AtlasApiError, getJson, postJson } from '../atlas-client.js';
+import { resolveEnvWithDiscovery } from '../config.js';
+import { isFullSha, requiresPinnedSha } from './pinning.js';
+const LOG = '[seq-studio]';
+const TERMINAL = new Set(['active', 'failed', 'retired']);
+async function envAndToken(args) {
+    const requested = typeof args.flags.e === 'string' ? args.flags.e : typeof args.flags.env === 'string' ? args.flags.env : undefined;
+    if (!requested) {
+        throw new Error('missing -e/--env <environment>');
+    }
+    const env = await resolveEnvWithDiscovery({ requested });
+    let token;
+    try {
+        token = await getAccessToken();
+    }
+    catch (error) {
+        if (error instanceof NotLoggedInError)
+            throw error;
+        throw error;
+    }
+    return { env, token };
+}
+function flagString(flags, key) {
+    const value = flags[key];
+    if (value === true)
+        throw new Error(`--${key} requires a value`);
+    return value;
+}
+/**
+ * The CLI's local dev-loop env is named `local` — chosen so `-e local` lines
+ * up with `seqapi -e local` / `artifact-studio --env local` (see `config.ts`
+ * `BUILT_IN_ENV_URLS`). There is no `local` in the server's deploy-lifecycle
+ * enum (`DEPLOY_ENVIRONMENTS` in `atlas/src/server/services/data-pipelines/schema.ts`
+ * is `dev | staging | production | banksouth`); the server's name for that
+ * same developer-loop target is `dev` (`targetFactsForEnvironment` treats
+ * `dev` as the one target exempt from a `lakebase_branch` binding). Map at
+ * this one boundary — every lifecycle request body funnels through here —
+ * so the CLI never sends the wire-invalid `local` and every other env name
+ * passes through unchanged.
+ */
+export function deployEnvironmentForEnv(env) {
+    return env.name === 'local' ? 'dev' : env.name;
+}
+export async function pipelinePlanCommand(args) {
+    const repo = flagString(args.flags, 'repo');
+    const ref = flagString(args.flags, 'ref');
+    if (!repo || !ref) {
+        console.error('usage: seq-studio pipeline plan --repo pipelines/<slug> --ref <sha|branch> -e <env> [--json]');
+        return 1;
+    }
+    const { env, token } = await envAndToken(args);
+    const json = args.flags.json === true || args.flags.json === 'true';
+    let response;
+    try {
+        response = await postJson({
+            baseUrl: env.url,
+            token,
+            path: '/api/data-pipelines/pipelines/plan',
+            body: { repo, ref, environment: deployEnvironmentForEnv(env) },
+        });
+    }
+    catch (error) {
+        if (error instanceof AtlasApiError) {
+            console.error(`${LOG} plan failed: ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+    if (json) {
+        console.log(JSON.stringify(response, null, 2));
+    }
+    else {
+        console.log(response.text);
+        printFindingsTable(response.plan.findings);
+    }
+    return response.plan.hasDestructive ? 1 : 0;
+}
+export async function pipelineDeployCommand(args) {
+    const repo = flagString(args.flags, 'repo');
+    const ref = flagString(args.flags, 'ref');
+    const deploymentId = flagString(args.flags, 'deployment-id');
+    const approvedBy = flagString(args.flags, 'approved-by');
+    const { env, token } = await envAndToken(args);
+    if (requiresPinnedSha(env.name) && ref && !isFullSha(ref)) {
+        console.error(`${LOG} deploy to ${env.name} requires a pinned 40-hex commit SHA (got '${ref}')`);
+        return 1;
+    }
+    let enqueue;
+    try {
+        if (deploymentId) {
+            // Direct execute of a persisted plan.
+            const stageId = flagString(args.flags, 'stage-id');
+            if (!stageId) {
+                console.error('usage: seq-studio pipeline deploy --deployment-id <id> --stage-id <id> -e <env> [--approved-by <sub>] [--no-wait]');
+                return 1;
+            }
+            enqueue = await postJson({
+                baseUrl: env.url,
+                token,
+                path: `/api/data-pipelines/stages/${stageId}/deploy`,
+                body: { deploymentId, ...(approvedBy ? { approvedBy } : {}) },
+            });
+        }
+        else {
+            if (!repo || !ref) {
+                console.error('usage: seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha> -e <env> [--approved-by <sub>] [--no-wait]');
+                return 1;
+            }
+            // Plan then deploy the first planning deployment.
+            const plan = await postJson({
+                baseUrl: env.url,
+                token,
+                path: '/api/data-pipelines/pipelines/plan',
+                body: { repo, ref, environment: deployEnvironmentForEnv(env) },
+            });
+            if (plan.plan.hasDestructive) {
+                console.error(`${LOG} plan has destructive findings — refusing to deploy`);
+                if (args.flags.json === true || args.flags.json === 'true') {
+                    console.log(JSON.stringify(plan, null, 2));
+                }
+                else {
+                    console.error(plan.text);
+                }
+                return 1;
+            }
+            const firstId = plan.deploymentIds[0];
+            const stageId = plan.stageIds[0];
+            if (!firstId || !stageId) {
+                console.error(`${LOG} plan produced no deployment rows`);
+                return 1;
+            }
+            enqueue = await postJson({
+                baseUrl: env.url,
+                token,
+                path: `/api/data-pipelines/stages/${stageId}/deploy`,
+                body: {
+                    deploymentId: firstId,
+                    ...(approvedBy ? { approvedBy } : {}),
+                },
+            });
+        }
+    }
+    catch (error) {
+        if (error instanceof AtlasApiError) {
+            console.error(`${LOG} deploy failed: ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+    console.log(`${LOG} enqueued deploy ${enqueue.deploymentId} (trigger=${enqueue.triggerRunId ?? 'n/a'})`);
+    if (args.flags['no-wait'] === true || args.flags['no-wait'] === 'true') {
+        return 0;
+    }
+    return pollDeployment({ baseUrl: env.url, token, deploymentId: enqueue.deploymentId });
+}
+export async function pipelinePromoteCommand(args) {
+    const stage = flagString(args.flags, 'stage');
+    const version = flagString(args.flags, 'version');
+    const repo = flagString(args.flags, 'repo');
+    const approvedBy = flagString(args.flags, 'approved-by');
+    if (!stage || !version) {
+        console.error('usage: seq-studio pipeline promote --stage <slug> --version <v> -e <env> [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]');
+        return 1;
+    }
+    const { env, token } = await envAndToken(args);
+    if (requiresPinnedSha(env.name) && !approvedBy) {
+        console.error(`${LOG} promote to ${env.name} requires --approved-by <your sub/email> (approvals are self-recorded)`);
+        return 1;
+    }
+    const stageId = await resolveStageIdBySlug({ baseUrl: env.url, token, slug: stage, repo });
+    let enqueue;
+    try {
+        enqueue = await postJson({
+            baseUrl: env.url,
+            token,
+            path: `/api/data-pipelines/stages/${stageId}/promote`,
+            body: {
+                version,
+                environment: deployEnvironmentForEnv(env),
+                ...(approvedBy ? { approvedBy } : {}),
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof AtlasApiError) {
+            console.error(`${LOG} promote failed: ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+    console.log(`${LOG} enqueued promote ${enqueue.deploymentId}`);
+    if (args.flags['no-wait'] === true || args.flags['no-wait'] === 'true')
+        return 0;
+    return pollDeployment({ baseUrl: env.url, token, deploymentId: enqueue.deploymentId });
+}
+export async function pipelineRunNowCommand(args) {
+    const stage = flagString(args.flags, 'stage');
+    const repo = flagString(args.flags, 'repo');
+    if (!stage) {
+        console.error('usage: seq-studio pipeline run-now --stage <slug> -e <env> [--repo pipelines/<slug>] [--json]');
+        return 1;
+    }
+    const { env, token } = await envAndToken(args);
+    const json = args.flags.json === true || args.flags.json === 'true';
+    let stageId;
+    try {
+        stageId = await resolveStageIdBySlug({ baseUrl: env.url, token, slug: stage, repo });
+    }
+    catch (error) {
+        console.error(`${LOG} ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+    let response;
+    try {
+        response = await postJson({
+            baseUrl: env.url,
+            token,
+            path: `/api/data-pipelines/stages/${stageId}/run`,
+            body: { environment: deployEnvironmentForEnv(env) },
+        });
+    }
+    catch (error) {
+        if (error instanceof AtlasApiError) {
+            console.error(`${LOG} run-now failed: ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+    if (json) {
+        console.log(JSON.stringify(response, null, 2));
+    }
+    else {
+        console.log(`${LOG} run-now ${stage} → ${deployEnvironmentForEnv(env)}`);
+        console.log(`${LOG} invocation ${response.invocationId} (${response.status})`);
+        console.log(`${LOG} ${response.databricks_url}`);
+    }
+    return 0;
+}
+export async function pipelineRollbackCommand(args) {
+    const stage = flagString(args.flags, 'stage');
+    const repo = flagString(args.flags, 'repo');
+    const approvedBy = flagString(args.flags, 'approved-by');
+    if (!stage) {
+        console.error('usage: seq-studio pipeline rollback --stage <slug> -e <env> [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]');
+        return 1;
+    }
+    const { env, token } = await envAndToken(args);
+    if (requiresPinnedSha(env.name) && !approvedBy) {
+        console.error(`${LOG} rollback in ${env.name} requires --approved-by <your sub/email> (approvals are explicit even for rollbacks)`);
+        return 1;
+    }
+    const stageId = await resolveStageIdBySlug({ baseUrl: env.url, token, slug: stage, repo });
+    let enqueue;
+    try {
+        enqueue = await postJson({
+            baseUrl: env.url,
+            token,
+            path: `/api/data-pipelines/stages/${stageId}/rollback`,
+            body: {
+                environment: deployEnvironmentForEnv(env),
+                ...(approvedBy ? { approvedBy } : {}),
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof AtlasApiError) {
+            console.error(`${LOG} rollback failed: ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+    console.log(`${LOG} enqueued rollback ${enqueue.deploymentId}`);
+    if (args.flags['no-wait'] === true || args.flags['no-wait'] === 'true')
+        return 0;
+    return pollDeployment({ baseUrl: env.url, token, deploymentId: enqueue.deploymentId });
+}
+function printFindingsTable(findings) {
+    if (findings.length === 0) {
+        console.log(`${LOG} no resource changes`);
+        return;
+    }
+    console.log(`${LOG} ${'CLASS'.padEnd(12)} ${'RESOURCE'.padEnd(32)} MESSAGE`);
+    for (const f of findings) {
+        const klass = f.destructiveReason
+            ? `${f.classification}/${f.destructiveReason}`
+            : f.classification;
+        console.log(`${LOG} ${klass.padEnd(12)} ${f.resourceKey.padEnd(32)} ${f.message}`);
+    }
+}
+async function pollDeployment({ baseUrl, token, deploymentId, }) {
+    const started = Date.now();
+    const timeoutMs = 15 * 60 * 1000;
+    while (Date.now() - started < timeoutMs) {
+        const detail = await getJson({
+            baseUrl,
+            token,
+            path: `/api/data-pipelines/deployments/${deploymentId}`,
+        });
+        console.log(`${LOG} deployment ${deploymentId}: ${detail.status}`);
+        if (TERMINAL.has(detail.status)) {
+            if (detail.status === 'active') {
+                console.log(`${LOG} deploy succeeded`);
+                return 0;
+            }
+            console.error(`${LOG} deploy ended '${detail.status}': ${detail.statusDetail ?? ''}`);
+            return 1;
+        }
+        await new Promise((r) => setTimeout(r, 2000));
+    }
+    console.error(`${LOG} timed out waiting for deployment ${deploymentId}`);
+    return 1;
+}
+/**
+ * Stage identity is `(repo, slug)` — a bare slug can be ambiguous across
+ * Pipelines. `--repo pipelines/<domain>` scopes the lookup server-side; an
+ * ambiguous bare slug fails with the candidate repos rather than guessing.
+ *
+ * The `slug` query param is an EXACT server-side filter (contracts.ts
+ * `listStagesQuerySchema`) — the list route's default sort is
+ * `updated_at DESC`, so scanning only the first page (as this used to do)
+ * silently missed a matching stage buried on a later page, and would have
+ * missed a same-slug duplicate on a later page too, falsely reporting the
+ * bare-slug lookup as unique (SEQ-2447 review). Filtering server-side by the
+ * exact slug means every match is guaranteed to fit on one page regardless
+ * of how many other stages exist.
+ */
+async function resolveStageIdBySlug({ baseUrl, token, slug, repo, }) {
+    const repoFilter = repo ? `&repo=${encodeURIComponent(repo)}` : '';
+    const listed = await getJson({
+        baseUrl,
+        token,
+        path: `/api/data-pipelines/stages?limit=200&slug=${encodeURIComponent(slug)}${repoFilter}`,
+    });
+    const first = listed.stages[0];
+    if (!first) {
+        throw new Error(`stage '${slug}' not found${repo ? ` in ${repo}` : ''}`);
+    }
+    if (listed.stages.length > 1) {
+        throw new Error(`stage '${slug}' exists in multiple Pipelines (${listed.stages.map((m) => m.repo).join(', ')}) — ` +
+            'disambiguate with --repo pipelines/<domain>');
+    }
+    return first.id;
+}

package/dist/pipeline/pinning.d.ts

@@ -0,0 +1,5 @@
+/** Client-side pin rules mirrored from the server deploy adapter (SEQ-2450). */
+export declare const FULL_SHA_PATTERN: RegExp;
+export declare const PINNED_ENVIRONMENTS: Set<string>;
+export declare function isFullSha(ref: string): boolean;
+export declare function requiresPinnedSha(environment: string): boolean;

package/dist/pipeline/pinning.js

@@ -0,0 +1,9 @@
+/** Client-side pin rules mirrored from the server deploy adapter (SEQ-2450). */
+export const FULL_SHA_PATTERN = /^[0-9a-f]{40}$/i;
+export const PINNED_ENVIRONMENTS = new Set(['production', 'banksouth']);
+export function isFullSha(ref) {
+    return FULL_SHA_PATTERN.test(ref);
+}
+export function requiresPinnedSha(environment) {
+    return PINNED_ENVIRONMENTS.has(environment);
+}

package/dist/pipeline/templates.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `seq-studio pipeline init` scaffolds — commented per-kind `<name>.stage.yml`
+ * templates plus an entrypoint stub. Kept as string constants (not a
+ * templates/ directory) so the pipeline family needs no copy step and works
+ * from any install of the CLI.
+ */
+export declare const STAGE_TYPES: readonly ["ingestion", "transformation", "serving"];
+export type StageTemplateType = (typeof STAGE_TYPES)[number];
+export declare function renderStageTemplate(name: string, type: StageTemplateType): string;
+/** Serving stages are declarative — no entrypoint stub. */
+export declare function renderEntrypointStub(name: string): string;

package/dist/pipeline/templates.js

@@ -0,0 +1,166 @@
+/**
+ * `seq-studio pipeline init` scaffolds — commented per-kind `<name>.stage.yml`
+ * templates plus an entrypoint stub. Kept as string constants (not a
+ * templates/ directory) so the pipeline family needs no copy step and works
+ * from any install of the CLI.
+ */
+const envelopeTemplate = (name, type) => `# ${name}.stage.yml — one deployable ${type} stage of this Pipeline.
+# Docs: @sequenceholdings/pipeline-spec (the schema is the single source of truth).
+schema_version: 1
+stage: ${name}
+title: TODO — one-line human title
+description: >-
+  TODO — what this stage does and why it exists.
+type: ${type}
+owners:
+  - you@seqholdings.com
+# critical | standard | experimental
+criticality: experimental
+# Optional reliability posture:
+# slos:
+#   freshness: PT4H        # ISO-8601 durations
+#   max_duration: PT1H
+# alerts:
+#   channels: [eng-alerts] # symbolic channel refs — never webhook URLs
+# runbook: https://notion.so/your-runbook
+environments:
+  - staging
+`;
+const INGESTION_BODY = `
+# Where the ingestion code runs: databricks (API pulls) | edge-worker (on-prem VM).
+# ('upload' is reserved — not yet supported.)
+runtime: databricks
+# databricks runtime pulls from an external system (symbolic refs, never secrets).
+# Secure-by-default: declare a credential family for authenticated APIs.
+# For genuinely keyless / public sources, omit credential entirely (do not
+# invent a sentinel binding) — e.g. source: { system: espn }.
+source:
+  system: my_source_system
+  credential: my_source_credential
+# edge-worker runtime instead binds a registered worker:
+# worker:
+#   machine: my_vm
+#   data_source: my_library
+#   credential: my_cred_family
+feeds:
+  # One feed = one stream of raw files into the volume landing zone.
+  # The platform derives (per-source catalog, never the deployment catalog):
+  # /Volumes/src_<source>/bronze/<feed>/batch_id=<ts>/, the bronze table
+  # src_<source>.bronze.<feed>, envelope columns (batch_id, ingested_at,
+  # source_system, content_hash), and a presence manifest for full_snapshot.
+  my_feed:
+    # full_snapshot | incremental | event_stream
+    snapshot_mode: full_snapshot
+    natural_key:
+      - id
+    # incremental feeds declare their cursor:
+    # cursor:
+    #   column: updated_at
+    #   encoding: yyyyddd   # extensible string — provider-neutral
+    # none | contains_pii
+    pii: none
+    # parquet | json | csv | custom ('xlsx' is reserved — not yet supported)
+    format: json
+    # format: custom requires a pure file→rows decoder (never writes tables):
+    # decoder: src/decoders/my_decoder.py
+schedule:
+  cron: "0 6 * * *"
+  tz: America/New_York
+# Max staleness before the freshness SLO breaches:
+freshness_slo: P1D
+# Raw-file replay buffer (not an archive):
+retention: P30D
+entrypoint: src/{{snake}}.py
+`;
+const TRANSFORMATION_BODY = `
+# dlt | spark-job | polars
+engine: dlt
+inputs:
+  # Reference upstream assets by stage + feed (ingestion) or output:
+  # - stage: my-ingest
+  #   feed: my_feed
+  # - stage: upstream-transform
+  #   output: silver.some_table
+  #   columns: [id, amount]        # the subset you consume (validated)
+  # Lakebase CDF reverse-sync input (columns REQUIRED, never inferred):
+  # - kind: lakebase_cdf
+  #   table: manual.my_overrides
+  #   fold: latest_state           # latest_state | events
+  #   columns:
+  #     id: { type: string, nullable: false, key: true }
+  []
+trigger:
+  # At least one of cron / after:
+  cron: "0 7 * * *"
+  # after: [my-ingest]
+outputs:
+  # Typed contracts — names must be silver.* or gold.*:
+  silver.{{snake}}:
+    columns:
+      id:
+        type: string
+        nullable: false
+        key: true
+      value:
+        type: int
+    # fail | quarantine (→ silver.{{snake}}__quarantine) | warn
+    on_type_violation: fail
+    # additive-only (default: breaking changes fail CI) | versioned
+    compatibility: additive-only
+    # overwrite | append | auto_cdc
+    write_pattern: overwrite
+entrypoint: src/{{snake}}.py
+`;
+const SERVING_BODY = `
+# The transformation output this stage serves:
+source:
+  stage: my-gold-stage
+  output: gold.my_table
+projection:
+  # The served contract (inline columns or schema_ref):
+  columns:
+    id:
+      type: uuid
+      nullable: false
+      key: true
+    name:
+      type: string
+  primary_key:
+    - id
+# SNAPSHOT | TRIGGERED | CONTINUOUS (overwrite-written sources: SNAPSHOT only)
+sync_mode: SNAPSHOT
+trigger:
+  after: my-gold-stage
+expose:
+  view: public.my_table
+# Optional ORM coupling ('managed' mode is reserved — not yet supported):
+# orm_binding:
+#   namespace: my_namespace
+#   table: my_table
+#   mode: referenced
+`;
+const ENTRYPOINT_STUB = `"""Entrypoint stub for the {{name}} stage.
+
+The platform invokes this per the stage spec ({{name}}.stage.yml).
+Decoders and transforms stay pure — bronze materialization, envelope
+stamping, and table writes are platform-owned.
+"""
+
+
+def main() -> None:
+    raise NotImplementedError("implement the {{name}} stage")
+
+
+if __name__ == "__main__":
+    main()
+`;
+export const STAGE_TYPES = ['ingestion', 'transformation', 'serving'];
+export function renderStageTemplate(name, type) {
+    const body = type === 'ingestion' ? INGESTION_BODY : type === 'transformation' ? TRANSFORMATION_BODY : SERVING_BODY;
+    return (envelopeTemplate(name, type) +
+        body.replace(/\{\{name\}\}/g, name).replace(/\{\{snake\}\}/g, name.replace(/-/g, '_')));
+}
+/** Serving stages are declarative — no entrypoint stub. */
+export function renderEntrypointStub(name) {
+    return ENTRYPOINT_STUB.replace(/\{\{name\}\}/g, name);
+}

package/dist/process/build.d.ts

@@ -18,4 +18,8 @@ export interface BuildBundleOptions {
     };
 }
 export declare function buildBundleFromProcesses(defs: readonly LoadedProcess[], options?: BuildBundleOptions): Promise<LatticeBundle>;
+export declare function finalizeCompiledBundle({ bundle, resolveProcessPin, }: {
+    bundle: LatticeBundle;
+    resolveProcessPin: ResolveProcessPin;
+}): Promise<LatticeBundle>;
 export declare function summarizeBundle(bundle: LatticeBundle): LatticeBundleSummary;

package/dist/process/build.js

@@ -27,6 +27,16 @@ export async function buildBundleFromProcesses(defs, options) {
     // the SDK so a CLI-built bundle is byte-identical to a server-applied one.
     return finalizeBundleIdentity({ processes, metadata });
 }
+export async function finalizeCompiledBundle({ bundle, resolveProcessPin, }) {
+    const processes = bundle.processes.map((process) => structuredClone(process));
+    const localProcessIds = new Set(processes.map((process) => process.id));
+    await resolveSubprocessPinsInProcesses(processes, async (processId, version) => {
+        if (!version && localProcessIds.has(processId))
+            return null;
+        return resolveProcessPin(processId, version);
+    });
+    return finalizeBundleIdentity({ processes, metadata: bundle.metadata });
+}
 async function resolveSubprocessPinsInProcesses(processes, resolve) {
     const pins = [];
     for (const proc of processes) {
@@ -86,8 +96,20 @@ function serializeProcess(input) {
         ...(input.process.supervisor_retry !== undefined
             ? { supervisor_retry: serializeRetryConfig(input.process.supervisor_retry) }
             : {}),
+        // Both run_as keys are omitted when unset so existing hashes stay stable
+        // (an email-only run_as serializes byte-identically to before the
+        // service_account field existed).
         ...(input.process.run_as !== undefined
-            ? { run_as: { email: input.process.run_as.email } }
+            ? {
+                run_as: {
+                    ...(input.process.run_as.email !== undefined
+                        ? { email: input.process.run_as.email }
+                        : {}),
+                    ...(input.process.run_as.service_account !== undefined
+                        ? { service_account: input.process.run_as.service_account }
+                        : {}),
+                },
+            }
             : {}),
     };
 }
@@ -135,6 +157,10 @@ function serializeNodeMetadata(node) {
                 meta.limits = native.limits;
             if (native.bindings)
                 meta.bindings = native.bindings;
+            // Per-node service-account override — omitted when unset for hash stability.
+            if (native.run_as?.service_account) {
+                meta.run_as = { service_account: native.run_as.service_account };
+            }
             const nativeInputMapper = native.input;
             if (typeof nativeInputMapper === 'function') {
                 meta.input_mapper_source = nativeInputMapper.toString();
@@ -164,8 +190,9 @@ function serializeNodeMetadata(node) {
             const human = node;
             const meta = {
                 metadata: human.metadata ?? {},
-                timeout: human.timeout ?? '7d',
             };
+            if (human.timeout !== undefined)
+                meta.timeout = human.timeout;
             if (human.on_timeout_edge_id)
                 meta.on_timeout_edge_id = human.on_timeout_edge_id;
             if (human.completeLabel)
@@ -327,6 +354,10 @@ function serializeNodeMetadata(node) {
                 meta.limits = mf.limits;
             if (mf.bindings)
                 meta.bindings = mf.bindings;
+            // Per-node service-account override — omitted when unset for hash stability.
+            if (mf.run_as?.service_account) {
+                meta.run_as = { service_account: mf.run_as.service_account };
+            }
             // NOTE: `middleware` (e.g. withRetry) is serialized generically for every
             // node kind in `serializeNode` above — don't duplicate it here.
             const inputMapper = mf.input;

package/dist/process/codegen.js

@@ -50,7 +50,16 @@ export function generateProcessFiles(process, bundle) {
             ? `  max_concurrent_runs: ${process.max_concurrent_runs},`
             : null,
         process.supervisor_retry !== undefined ? `  supervisor_retry: ${pretty(process.supervisor_retry, 1)},` : null,
-        process.run_as !== undefined ? `  run_as: { email: ${lit(process.run_as.email)} },` : null,
+        process.run_as !== undefined
+            ? `  run_as: { ${[
+                process.run_as.email !== undefined ? `email: ${lit(process.run_as.email)}` : null,
+                process.run_as.service_account !== undefined
+                    ? `service_account: ${lit(process.run_as.service_account)}`
+                    : null,
+            ]
+                .filter((f) => f !== null)
+                .join(', ')} },`
+            : null,
         Array.isArray(process.tags) && process.tags.length > 0
             ? `  tags: ${pretty(process.tags, 1)},`
             : null,
@@ -125,6 +134,7 @@ function emitNode(node, ctx) {
                 `  function: ${lit(String(m.registered_function_id))},`,
                 m.config !== undefined ? `  config: ${pretty(m.config, 1)},` : null,
                 m.limits !== undefined ? `  limits: ${pretty(m.limits, 1)},` : null,
+                runAsField(m.run_as),
                 bindings(m.bindings),
                 middleware(m.middleware),
                 mapper('input', m.input_mapper_source),
@@ -189,6 +199,7 @@ function emitNode(node, ctx) {
                 `  function: ${lit(String(m.function_id))},`,
                 m.version ? `  version: ${lit(String(m.version))},` : null,
                 m.limits !== undefined ? `  limits: ${pretty(m.limits, 1)},` : null,
+                runAsField(m.run_as),
                 bindings(m.bindings),
                 middleware(m.middleware),
                 mapper('input', m.input_mapper_source),
@@ -209,6 +220,13 @@ function emitEdges(edges) {
     const items = edges.map((e) => `{ id: ${lit(e.id)}, to: ${lit(e.to)} }`).join(', ');
     return `[${items}] as const`;
 }
+/** Per-node service-account override — `metadata.run_as.service_account`. */
+function runAsField(runAs) {
+    const sa = runAs?.service_account;
+    if (typeof sa !== 'string' || sa.length === 0)
+        return null;
+    return `  run_as: { service_account: ${lit(sa)} },`;
+}
 /** A mapper field whose value is a serialized `Function.toString()` string. */
 function mapper(field, source) {
     if (typeof source !== 'string' || source.length === 0)