@shipfox/expression 1.1.0

package/dist/workflow-context/workflow-context.js

@@ -0,0 +1,664 @@
+import { outputDeclarationsToExpressionFields } from '../outputs/output-declarations.js';
+export const workflowContextNames = [
+    'run',
+    'trigger',
+    'event',
+    'inputs',
+    'job',
+    'executions',
+    'execution',
+    'jobs',
+    'needs',
+    'steps',
+    'step',
+    'vars',
+    'secrets'
+];
+export const availabilitySites = [
+    // Server receives an external trigger or manual request before a run row exists.
+    'ingest',
+    // Server creates the workflow run and its run-scoped context.
+    'run-creation',
+    // Server creates a concrete job execution and its execution-scoped context.
+    'execution-creation',
+    // Server activates a queued job after dependencies, matrix expansion, and runner demand are known.
+    'job-activation',
+    // Server dispatches a job step to a runner with all server-filled context resolved.
+    'step-dispatch',
+    // Server receives a step report and makes step result context available.
+    'step-report',
+    // Server resolves one job execution after its steps have settled.
+    'execution-resolution',
+    // Server resolves the job after all of its executions are known.
+    'job-resolution'
+];
+export const runnerFillTarget = 'runner-fill';
+export const workflowContextSensitivities = [
+    'persistable',
+    'ephemeral'
+];
+export const workflowContextHosts = [
+    'server',
+    'runner'
+];
+export const workflowContextReservedRoots = {
+    matrix: {
+        host: 'server',
+        availability: 'job-activation'
+    },
+    runner: {
+        host: 'runner'
+    }
+};
+export const workflowContextTrustTiers = [
+    'trusted',
+    'untrusted'
+];
+const runTypeEnvironment = {
+    run: {
+        kind: 'object',
+        fields: {
+            id: 'string',
+            name: 'string',
+            definition_id: 'string',
+            project_id: 'string',
+            workspace_id: 'string',
+            created_at: 'timestamp'
+        }
+    }
+};
+const triggerTypeEnvironment = {
+    trigger: {
+        kind: 'object',
+        fields: {
+            source: 'string',
+            event: 'string'
+        }
+    }
+};
+const jobTypeEnvironment = {
+    job: {
+        kind: 'object',
+        fields: {
+            key: 'string'
+        }
+    }
+};
+const executionEventType = {
+    kind: 'object',
+    fields: {
+        source: 'string',
+        event: 'string',
+        delivery_id: 'string',
+        received_at: 'timestamp',
+        data: {
+            kind: 'object',
+            fields: {}
+        }
+    }
+};
+const executionType = {
+    kind: 'object',
+    fields: {
+        index: 'int',
+        name: 'string',
+        status: 'string',
+        failed: 'bool',
+        started_at: 'timestamp',
+        finished_at: 'timestamp',
+        events: {
+            kind: 'list',
+            element: executionEventType
+        },
+        outputs: {
+            kind: 'map'
+        }
+    }
+};
+const executionsTypeEnvironment = {
+    executions: {
+        kind: 'list',
+        element: executionType
+    }
+};
+const executionTypeEnvironment = {
+    execution: executionType
+};
+const stepGateType = {
+    kind: 'object',
+    fields: {
+        passed: 'bool',
+        source: 'string',
+        reason: 'string',
+        exit_code: 'int'
+    }
+};
+const stepAttemptType = {
+    kind: 'object',
+    fields: {
+        status: 'string',
+        exit_code: 'int',
+        outputs: {
+            kind: 'map'
+        },
+        response: 'string',
+        gate: stepGateType
+    }
+};
+const stepEntityType = {
+    kind: 'object',
+    fields: {
+        ...stepAttemptType.fields,
+        attempts: {
+            kind: 'list',
+            element: stepAttemptType
+        }
+    }
+};
+const stepTypeEnvironment = {
+    step: {
+        kind: 'object',
+        fields: {
+            attempt: 'int',
+            is_retry: 'bool',
+            restart: {
+                kind: 'object',
+                fields: {
+                    from: stepEntityType,
+                    feedback: 'string'
+                }
+            },
+            exit_code: 'int',
+            status: 'string',
+            outputs: {
+                kind: 'map'
+            }
+        }
+    }
+};
+export function buildTypedRootsEnvironment(params) {
+    return {
+        ...params.steps === undefined ? {} : {
+            steps: stepsRootType(params.steps)
+        },
+        ...params.currentStep === undefined ? {} : {
+            step: selfStepType(params.currentStep)
+        },
+        ...params.jobs === undefined ? {} : {
+            jobs: jobsRootType(params.jobs)
+        },
+        ...params.needs === undefined ? {} : {
+            needs: needsRootType()
+        }
+    };
+}
+export const workflowContextDefinitions = {
+    run: {
+        availability: 'run-creation',
+        trustTier: 'trusted',
+        sensitivity: 'persistable',
+        host: 'server',
+        shape: 'known',
+        checkMode: 'typed',
+        typeEnvironment: runTypeEnvironment
+    },
+    trigger: {
+        availability: 'ingest',
+        trustTier: 'trusted',
+        sensitivity: 'persistable',
+        host: 'server',
+        shape: 'known',
+        checkMode: 'typed',
+        typeEnvironment: triggerTypeEnvironment
+    },
+    event: {
+        availability: 'ingest',
+        trustTier: 'untrusted',
+        sensitivity: 'persistable',
+        host: 'server',
+        shape: 'open',
+        checkMode: 'syntax'
+    },
+    inputs: {
+        availability: 'run-creation',
+        trustTier: 'untrusted',
+        sensitivity: 'persistable',
+        host: 'server',
+        shape: 'open',
+        checkMode: 'syntax'
+    },
+    job: {
+        availability: 'run-creation',
+        trustTier: 'trusted',
+        sensitivity: 'persistable',
+        host: 'server',
+        shape: 'known',
+        checkMode: 'typed',
+        typeEnvironment: jobTypeEnvironment
+    },
+    executions: {
+        availability: 'execution-creation',
+        trustTier: 'trusted',
+        sensitivity: 'persistable',
+        host: 'server',
+        shape: 'known',
+        checkMode: 'typed',
+        typeEnvironment: executionsTypeEnvironment,
+        untrustedPaths: [
+            'events'
+        ]
+    },
+    execution: {
+        availability: 'execution-creation',
+        trustTier: 'trusted',
+        sensitivity: 'persistable',
+        host: 'server',
+        shape: 'known',
+        checkMode: 'typed',
+        typeEnvironment: executionTypeEnvironment,
+        untrustedPaths: [
+            'events'
+        ]
+    },
+    jobs: {
+        availability: 'job-activation',
+        trustTier: 'untrusted',
+        sensitivity: 'persistable',
+        host: 'server',
+        shape: 'open',
+        checkMode: 'syntax'
+    },
+    needs: {
+        availability: 'job-activation',
+        trustTier: 'untrusted',
+        sensitivity: 'persistable',
+        host: 'server',
+        shape: 'known',
+        checkMode: 'typed',
+        typeEnvironment: {
+            needs: {
+                kind: 'list',
+                element: jobEntityType({
+                    key: '$need'
+                })
+            }
+        }
+    },
+    steps: {
+        availability: 'step-dispatch',
+        trustTier: 'trusted',
+        sensitivity: 'persistable',
+        host: 'server',
+        shape: 'open',
+        checkMode: 'syntax'
+    },
+    step: {
+        availability: 'step-dispatch',
+        trustTier: 'trusted',
+        sensitivity: 'persistable',
+        host: 'server',
+        shape: 'known',
+        checkMode: 'typed',
+        typeEnvironment: stepTypeEnvironment,
+        untrustedPaths: [
+            'outputs'
+        ]
+    },
+    vars: {
+        availability: 'run-creation',
+        trustTier: 'trusted',
+        sensitivity: 'persistable',
+        host: 'server',
+        shape: 'open',
+        checkMode: 'syntax',
+        literalKeyOnly: true
+    },
+    secrets: {
+        trustTier: 'trusted',
+        sensitivity: 'ephemeral',
+        host: 'runner',
+        shape: 'open',
+        checkMode: 'syntax',
+        literalKeyOnly: true
+    }
+};
+export const workflowFieldFailurePolicies = [
+    'fail',
+    'degrade',
+    'fail-closed'
+];
+const trustedOnlyTrustTiers = [
+    'trusted'
+];
+const anyTrustTier = [
+    'trusted',
+    'untrusted'
+];
+const serverOnlyHosts = [
+    'server'
+];
+const anyHost = [
+    'server',
+    'runner'
+];
+export const workflowInterpolationFieldPolicies = {
+    run: {
+        acceptedTrustTiers: trustedOnlyTrustTiers,
+        acceptedHosts: anyHost,
+        failurePolicy: 'fail',
+        renderSanitize: false
+    },
+    'env.value': {
+        acceptedTrustTiers: anyTrustTier,
+        acceptedHosts: anyHost,
+        failurePolicy: 'fail',
+        renderSanitize: false
+    },
+    'agent.prompt': {
+        acceptedTrustTiers: anyTrustTier,
+        acceptedHosts: serverOnlyHosts,
+        failurePolicy: 'fail',
+        renderSanitize: false
+    },
+    'agent.model': {
+        acceptedTrustTiers: trustedOnlyTrustTiers,
+        acceptedHosts: serverOnlyHosts,
+        failurePolicy: 'fail',
+        renderSanitize: false
+    },
+    'agent.provider': {
+        acceptedTrustTiers: trustedOnlyTrustTiers,
+        acceptedHosts: serverOnlyHosts,
+        failurePolicy: 'fail',
+        renderSanitize: false
+    },
+    'agent.thinking': {
+        acceptedTrustTiers: trustedOnlyTrustTiers,
+        acceptedHosts: serverOnlyHosts,
+        failurePolicy: 'fail',
+        renderSanitize: false
+    },
+    'job.runner': {
+        acceptedTrustTiers: anyTrustTier,
+        acceptedHosts: serverOnlyHosts,
+        failurePolicy: 'fail',
+        renderSanitize: false
+    },
+    'job.outputs': {
+        acceptedTrustTiers: anyTrustTier,
+        acceptedHosts: serverOnlyHosts,
+        failurePolicy: 'fail',
+        renderSanitize: false,
+        minimumFillTarget: 'execution-resolution'
+    },
+    'job.name': {
+        acceptedTrustTiers: anyTrustTier,
+        acceptedHosts: serverOnlyHosts,
+        failurePolicy: 'degrade',
+        renderSanitize: true
+    },
+    'step.name': {
+        acceptedTrustTiers: anyTrustTier,
+        acceptedHosts: serverOnlyHosts,
+        failurePolicy: 'degrade',
+        renderSanitize: true
+    },
+    'step.feedback': {
+        acceptedTrustTiers: anyTrustTier,
+        acceptedHosts: serverOnlyHosts,
+        failurePolicy: 'fail',
+        renderSanitize: false
+    }
+};
+export const workflowInterpolationFields = Object.keys(workflowInterpolationFieldPolicies);
+export const workflowPredicateFields = [
+    'step.success',
+    'job.success',
+    'trigger.filter',
+    'listener.on',
+    'listener.until',
+    'job.if',
+    'step.if'
+];
+export const workflowPredicateFieldFailurePolicy = 'fail-closed';
+const workflowPredicateFieldMinimumFillTargets = {
+    'step.success': 'step-report',
+    'job.success': 'job-resolution',
+    'trigger.filter': 'ingest',
+    'listener.on': 'job-activation',
+    'listener.until': 'job-activation',
+    'job.if': 'job-activation',
+    'step.if': 'step-dispatch'
+};
+export function getWorkflowContextDefinition(name) {
+    return workflowContextDefinitions[name];
+}
+export function getWorkflowContextAvailability(name) {
+    const definition = workflowContextDefinitions[name];
+    return definition.host === 'server' ? definition.availability : undefined;
+}
+export function getWorkflowContextHost(name) {
+    return workflowContextDefinitions[name].host;
+}
+export function resolveContextRootHost(root) {
+    if (isWorkflowContextName(root)) return workflowContextDefinitions[root].host;
+    if (isWorkflowContextReservedRoot(root)) return workflowContextReservedRoots[root].host;
+    return undefined;
+}
+export function resolveContextRootAvailability(root) {
+    if (isWorkflowContextName(root)) {
+        const definition = workflowContextDefinitions[root];
+        return definition.host === 'server' ? definition.availability : undefined;
+    }
+    if (!isWorkflowContextReservedRoot(root)) return undefined;
+    const reservedRoot = workflowContextReservedRoots[root];
+    return reservedRoot.host === 'server' ? reservedRoot.availability : undefined;
+}
+export function getWorkflowContextSensitivity(name) {
+    return workflowContextDefinitions[name].sensitivity;
+}
+export function rootsAvailableAt(site) {
+    const targetSiteIndex = availabilitySites.indexOf(site);
+    return workflowContextNames.filter((name)=>{
+        const definition = workflowContextDefinitions[name];
+        return definition.host === 'server' && availabilitySites.indexOf(definition.availability) <= targetSiteIndex;
+    });
+}
+export function unavailableRootsAt(roots, site) {
+    const availableRoots = new Set(rootsAvailableAt(site));
+    return roots.filter((root)=>!availableRoots.has(root));
+}
+export function getWorkflowContextTypeEnvironment(name) {
+    const context = getWorkflowContextDefinition(name);
+    return context.shape === 'known' ? context.typeEnvironment : undefined;
+}
+export function getWorkflowContextUntrustedPaths(name) {
+    const context = getWorkflowContextDefinition(name);
+    return context.shape === 'known' ? context.untrustedPaths : undefined;
+}
+export function workflowInterpolationFieldAcceptsTrustTier(field, trustTier) {
+    return workflowInterpolationFieldPolicies[field].acceptedTrustTiers.includes(trustTier);
+}
+export function workflowInterpolationFieldAcceptsHost(field, host) {
+    return workflowInterpolationFieldPolicies[field].acceptedHosts.includes(host);
+}
+export function workflowInterpolationFieldAcceptsContext(field, context) {
+    return workflowInterpolationFieldAcceptsTrustTier(field, workflowContextDefinitions[context].trustTier);
+}
+export function workflowContextRootRequiresLiteralKey(root) {
+    if (!isWorkflowContextName(root)) return false;
+    const definition = workflowContextDefinitions[root];
+    return 'literalKeyOnly' in definition && definition.literalKeyOnly === true;
+}
+export function getWorkflowInterpolationFieldFailurePolicy(field) {
+    return workflowInterpolationFieldPolicies[field].failurePolicy;
+}
+export function getWorkflowInterpolationFieldMinimumFillTarget(field) {
+    const policy = workflowInterpolationFieldPolicies[field];
+    return 'minimumFillTarget' in policy ? policy.minimumFillTarget : undefined;
+}
+export function getWorkflowPredicateFieldMinimumFillTarget(field) {
+    return workflowPredicateFieldMinimumFillTargets[field];
+}
+export function workflowContextAvailabilityReference() {
+    return [
+        ...workflowContextNames.map((root)=>{
+            const definition = workflowContextDefinitions[root];
+            if (definition.host === 'runner') return noServerAvailabilityReferenceEntry(root, false);
+            return availabilityReferenceEntry(root, definition.availability, false);
+        }),
+        ...Object.entries(workflowContextReservedRoots).map(([root, definition])=>{
+            if (definition.host === 'runner') {
+                return noServerAvailabilityReferenceEntry(root, true);
+            }
+            return availabilityReferenceEntry(root, definition.availability, true);
+        })
+    ];
+}
+function availabilityReferenceEntry(root, availability, reserved) {
+    const availabilityIndex = availabilitySites.indexOf(availability);
+    const availableAt = Object.fromEntries(availabilitySites.map((site)=>[
+            site,
+            availabilitySites.indexOf(site) >= availabilityIndex
+        ]));
+    return {
+        root,
+        availability,
+        reserved,
+        availableAt
+    };
+}
+function noServerAvailabilityReferenceEntry(root, reserved) {
+    const availableAt = Object.fromEntries(availabilitySites.map((site)=>[
+            site,
+            false
+        ]));
+    return {
+        root,
+        reserved,
+        availableAt
+    };
+}
+function stepsRootType(steps) {
+    return {
+        kind: 'object',
+        fields: Object.fromEntries(steps.map((step)=>[
+                step.key,
+                stepEntityTypeForStep(step)
+            ]))
+    };
+}
+function stepEntityTypeForStep(step) {
+    const attemptType = stepAttemptTypeForOutputs(outputsTypeForStep(step));
+    return {
+        kind: 'object',
+        fields: {
+            ...attemptType.fields,
+            attempts: {
+                kind: 'list',
+                element: attemptType
+            }
+        }
+    };
+}
+function selfStepType(step) {
+    return {
+        kind: 'object',
+        fields: {
+            ...stepTypeEnvironment.step.fields,
+            outputs: outputsTypeForStep(step)
+        }
+    };
+}
+function stepAttemptTypeForOutputs(outputs) {
+    return {
+        kind: 'object',
+        fields: {
+            ...stepAttemptType.fields,
+            outputs
+        }
+    };
+}
+function outputsTypeForStep(step) {
+    if (step.outputs === undefined) return {
+        kind: 'map'
+    };
+    return {
+        kind: 'object',
+        fields: outputDeclarationsToExpressionFields(step.outputs)
+    };
+}
+function jobsRootType(jobs) {
+    return {
+        kind: 'object',
+        fields: Object.fromEntries(jobs.map((job)=>[
+                job.key,
+                jobEntityType(job)
+            ]))
+    };
+}
+function needsRootType() {
+    return {
+        kind: 'list',
+        element: jobEntityTypeForNeeds()
+    };
+}
+function jobEntityTypeForNeeds() {
+    return {
+        kind: 'object',
+        fields: {
+            key: 'string',
+            status: 'string',
+            outputs: {
+                kind: 'map'
+            },
+            executions: {
+                kind: 'list',
+                element: executionTypeWithOutputs({
+                    kind: 'map'
+                })
+            }
+        }
+    };
+}
+function jobEntityType(job) {
+    const outputs = jobOutputsType(job);
+    const execution = executionTypeWithOutputs(outputs);
+    return {
+        kind: 'object',
+        fields: {
+            key: 'string',
+            status: 'string',
+            outputs,
+            executions: {
+                kind: 'list',
+                element: execution
+            }
+        }
+    };
+}
+function jobOutputsType(job) {
+    return job.outputs === undefined ? {
+        kind: 'map'
+    } : {
+        kind: 'object',
+        fields: job.outputs
+    };
+}
+function executionTypeWithOutputs(outputs) {
+    return {
+        kind: 'object',
+        fields: {
+            ...executionType.fields,
+            outputs
+        }
+    };
+}
+function isWorkflowContextName(root) {
+    return Object.hasOwn(workflowContextDefinitions, root);
+}
+function isWorkflowContextReservedRoot(root) {
+    return Object.hasOwn(workflowContextReservedRoots, root);
+}
+
+//# sourceMappingURL=workflow-context.js.map