@sanity/workflow-engine 0.32.0 → 0.33.0

package/dist/index.cjs

@@ -81,6 +81,10 @@ function effectiveEditable(baseline, override) {
 
 const DEFAULT_EDIT_MODE = "set";
 
+function _fieldTargetLabel(target) {
+    return [ target.scope, target.activity, target.field ].filter(Boolean).join(".");
+}
+
 function fieldSites(definition, stage) {
     const sites = [];
     for (const entry of definition.fields ?? []) sites.push({
@@ -1057,6 +1061,7 @@ function describeSiteHeading(address, ctx) {
         }
 
       case "action":
+      case "action-when":
         {
             const title = actionTitle(address, ctx), activity = activityTitle(address.activity, ctx);
             return groqConditionDescribe.phrase(id, {
@@ -1064,7 +1069,7 @@ function describeSiteHeading(address, ctx) {
                     title: title,
                     activity: activity
                 },
-                text: `action ${groqConditionDescribe.quoted(title)} on ${groqConditionDescribe.quoted(activity)} is available when:`
+                text: `action ${groqConditionDescribe.quoted(title)} on ${groqConditionDescribe.quoted(activity)} ${address.kind === "action" ? "is available" : "fires automatically"} when:`
             });
         }
 
@@ -1091,18 +1096,6 @@ function describeSiteHeading(address, ctx) {
             });
         }
 
-      case "action-when":
-        {
-            const title = actionTitle(address, ctx), activity = activityTitle(address.activity, ctx);
-            return groqConditionDescribe.phrase(id, {
-                params: {
-                    title: title,
-                    activity: activity
-                },
-                text: `action ${groqConditionDescribe.quoted(title)} on ${groqConditionDescribe.quoted(activity)} fires automatically when:`
-            });
-        }
-
       case "editable-field":
         {
             const field = fieldTitleOf({
@@ -1146,6 +1139,7 @@ function describeSite(site, ctx) {
         }
 
       case "action":
+      case "action-when":
         {
             const title = actionTitle(site, ctx), activity = activityTitle(site.activity, ctx);
             return groqConditionDescribe.phrase(id, {
@@ -1153,7 +1147,7 @@ function describeSite(site, ctx) {
                     title: title,
                     activity: activity
                 },
-                text: `the ${groqConditionDescribe.quoted(title)} action on ${groqConditionDescribe.quoted(activity)}`
+                text: `the ${groqConditionDescribe.quoted(title)} ${site.kind === "action" ? "action" : "trigger"} on ${groqConditionDescribe.quoted(activity)}`
             });
         }
 
@@ -1169,18 +1163,6 @@ function describeSite(site, ctx) {
             });
         }
 
-      case "action-when":
-        {
-            const title = actionTitle(site, ctx), activity = activityTitle(site.activity, ctx);
-            return groqConditionDescribe.phrase(id, {
-                params: {
-                    title: title,
-                    activity: activity
-                },
-                text: `the ${groqConditionDescribe.quoted(title)} trigger on ${groqConditionDescribe.quoted(activity)}`
-            });
-        }
-
       case "activity-filter":
         {
             const activity = activityTitle(site.activity, ctx);
@@ -1238,10 +1220,10 @@ function unsatisfiedTransitionSummaries(evaluation) {
         definition: evaluation.definition
     };
     return evaluation.currentStage.transitions.filter(t => !t.whenSatisfied).flatMap(t => {
-        const summary = describeCondition(t.insight, ctx).summary;
-        return summary !== void 0 ? [ {
+        const summary2 = describeCondition(t.insight, ctx).summary;
+        return summary2 !== void 0 ? [ {
             transition: t.transition.name,
-            summary: summary
+            summary: summary2
         } ] : [];
     });
 }
@@ -2872,8 +2854,8 @@ class CascadeLimitError extends invariants.WorkflowError {
 
 const FIELD_OP_TYPES = [ "field.set", "field.setIfMissing", "field.unset", "field.append", "field.inc", "field.dec", "field.updateWhere", "field.removeWhere" ];
 
-function isFieldOp(summary) {
-    return FIELD_OP_TYPES.includes(summary.opType);
+function isFieldOp(summary2) {
+    return FIELD_OP_TYPES.includes(summary2.opType);
 }
 
 function validateActionParams({action: action, activityName: activityName, callerParams: callerParams}) {
@@ -2952,7 +2934,7 @@ async function runOps(args) {
     if (ops === void 0 || ops.length === 0) return [];
     const opsFromDefinition = origin.effect === void 0 && origin.edit !== !0, summaries = [];
     for (const op of ops) {
-        const summary = await applyOp(op, {
+        const summary2 = await applyOp(op, {
             mutation: mutation,
             stage: stage,
             activityName: origin.activity,
@@ -2966,9 +2948,9 @@ async function runOps(args) {
             memberRoles: args.memberRoles,
             roleAliases: args.roleAliases
         });
-        summaries.push(summary), shouldRecordOpApplied(summary) && mutation.history.push(opAppliedEntry({
+        summaries.push(summary2), shouldRecordOpApplied(summary2) && mutation.history.push(opAppliedEntry({
             origin: origin,
-            summary: summary,
+            summary: summary2,
             stage: stage,
             actor: actor,
             now: now
@@ -2977,12 +2959,12 @@ async function runOps(args) {
     return summaries;
 }
 
-function shouldRecordOpApplied(summary) {
-    return summary.opType !== "field.setIfMissing" || summary.resolved !== void 0;
+function shouldRecordOpApplied(summary2) {
+    return summary2.opType !== "field.setIfMissing" || summary2.resolved !== void 0;
 }
 
 function opAppliedEntry(args) {
-    const {origin: origin, summary: summary, stage: stage, actor: actor, now: now} = args;
+    const {origin: origin, summary: summary2, stage: stage, actor: actor, now: now} = args;
     return {
         _key: randomKey(),
         _type: "opApplied",
@@ -3000,12 +2982,12 @@ function opAppliedEntry(args) {
         ...origin.effect !== void 0 ? {
             effect: origin.effect
         } : {},
-        opType: summary.opType,
-        ...summary.target !== void 0 ? {
-            target: summary.target
+        opType: summary2.opType,
+        ...summary2.target !== void 0 ? {
+            target: summary2.target
         } : {},
-        ...summary.resolved !== void 0 ? {
-            resolved: summary.resolved
+        ...summary2.resolved !== void 0 ? {
+            resolved: summary2.resolved
         } : {},
         ...actor !== void 0 ? {
             actor: actor
@@ -3782,7 +3764,13 @@ function siblingConfig(target) {
     };
 }
 
-const wallClock = () => /* @__PURE__ */ (new Date).toISOString();
+const wallClock = () => /* @__PURE__ */ (new Date).toISOString(), tick = ms => new Promise(resolve => {
+    setTimeout(resolve, ms);
+}), wallSleeper = async ms => {
+    let left = ms;
+    for (;left > 2147483647; ) await tick(2147483647), left -= 2147483647;
+    await tick(left);
+};
 
 function addMs(instant, ms) {
     return new Date(Date.parse(instant) + ms).toISOString();
@@ -3792,7 +3780,7 @@ function hasPassed(instant, now) {
     return Date.parse(instant) <= Date.parse(now);
 }
 
-const DATA_MODEL_VERSION = 9, DATA_MODEL_MIN_READER = 4, DATA_MODEL_MAX_READER = 9, READER_MODEL_ROLLOUT_URL = "https://www.sanity.io/docs/workflows/prerelease";
+const DATA_MODEL_VERSION = 10, DATA_MODEL_MIN_READER = 4, DATA_MODEL_MAX_READER = 10, READER_MODEL_ROLLOUT_URL = "https://www.sanity.io/docs/workflows/prerelease";
 
 class ReaderModelAcknowledgementError extends invariants.WorkflowError {
     code="WORKFLOW_READER_MODEL_ACKNOWLEDGEMENT_MISMATCH";
@@ -3948,6 +3936,22 @@ const DATA_MODEL_CHANGES = Object.freeze([ Object.freeze({
     compatibility: "reader-floor",
     applicability: "detectable",
     summary: "Singular assignee fields use member lists with at most one user and any number of roles."
+}), Object.freeze({
+    id: "required-content-references",
+    introducedInModel: 10,
+    minReaderModel: 10,
+    documentTypes: Object.freeze([ "definition", "instance" ]),
+    compatibility: "reader-floor",
+    applicability: "detectable",
+    summary: "Required content references must remain readable after initialization before actions or transitions advance."
+}), Object.freeze({
+    id: "effect-retry-policy",
+    introducedInModel: 10,
+    minReaderModel: 10,
+    documentTypes: Object.freeze([ "definition", "instance" ]),
+    compatibility: "reader-floor",
+    applicability: "detectable",
+    summary: "An effect node declares a bounded retry policy the engine enforces on every runtime."
 }) ]);
 
 function recordOf(value) {
@@ -4079,6 +4083,10 @@ function hasSingularAssigneeLists(document) {
     return typeof snapshot?.modelVersion == "number" && isAssignmentListModel(snapshot.modelVersion) && persistedFieldEntries(document).some(entry => entryHasKind(entry, "assignee"));
 }
 
+function hasEffectRetryPolicy(document) {
+    return persistedDefinitionTree(document)?.actions.some(action => recordsAt(action, "effects").some(effect => recordOf(effect.retry) !== void 0)) ?? !1;
+}
+
 function isMutationGuardAction(action) {
     return typeof action == "string" && invariants.MUTATION_GUARD_ACTIONS.some(candidate => candidate === action);
 }
@@ -4090,6 +4098,10 @@ function hasSplitGuardIdSpaces(document) {
     })) ?? !1;
 }
 
+function hasRequiredContentReferences(document) {
+    return persistedDefinitionTree(document)?.roots.some(root => recordsAt(root, "fields").some(field => field.required === !0 && typeof field.type == "string" && invariants.refKindAcceptsTypes(field.type))) ?? !1;
+}
+
 const featureDetectors = {
     "governed-model-stamps": () => !0,
     "subject-field-kind": document => hasFieldKind(document, "subject"),
@@ -4104,6 +4116,8 @@ const featureDetectors = {
     "role-constrained-assignment-fields": hasRoleConstrainedAssignments,
     "singular-assignee-lists": hasSingularAssigneeLists,
     "split-guard-id-spaces": hasSplitGuardIdSpaces,
+    "required-content-references": hasRequiredContentReferences,
+    "effect-retry-policy": hasEffectRetryPolicy,
     "node-semantics": hasNodeSemantics,
     "field-patch-ops": document => hasPersistedOpType(document, [ "field.inc", "field.dec", "field.setIfMissing" ]),
     "attributes-condition-var": () => !0
@@ -4340,9 +4354,13 @@ function abortReason(instance) {
 }
 
 function diagnoseInputFromEvaluation(evaluation) {
+    if (evaluation.missingDocuments?.length && evaluation.blockingMissingDocuments === void 0) throw new Error("Missing blocking document evidence in workflow evaluation");
     const stage = openStage(evaluation.instance);
     return {
         instance: evaluation.instance,
+        ...evaluation.missingDocuments !== void 0 ? {
+            missingDocuments: evaluation.blockingMissingDocuments ?? []
+        } : {},
         activities: evaluation.currentStage.activities,
         transitions: evaluation.currentStage.transitions,
         assignees: Object.fromEntries(evaluation.currentStage.activities.map(t => [ t.activity.name, assigneesOf(stage, t.activity.name) ]))
@@ -4461,7 +4479,7 @@ function diagnoseInstance(input) {
         at: instance.completedAt,
         ...liveChildrenField(instance)
     };
-    const cause = stuckFromDocumentState(input) ?? noTransitionFiresCause(input);
+    const cause = stuckFromDocumentState(input) ?? missingDocumentCause(input.missingDocuments) ?? noTransitionFiresCause(input);
     return cause !== void 0 ? {
         state: "stuck",
         cause: cause
@@ -4470,10 +4488,27 @@ function diagnoseInstance(input) {
     };
 }
 
+function missingDocumentCause(documents = []) {
+    return documents.length > 0 ? {
+        kind: "document-missing",
+        documents: documents
+    } : void 0;
+}
+
+function _additionalMissingDocuments(diagnosis, documents) {
+    return diagnosis.state === "stuck" && diagnosis.cause.kind !== "document-missing" ? documents ?? [] : [];
+}
+
 const RUNNABLE_VERBS = /* @__PURE__ */ new Set([ "set-stage", "abort", "drain-effects", "reset-activity" ]);
 
 function remediationsForCause(cause) {
     switch (cause.kind) {
+      case "document-missing":
+        return [ {
+            verb: "abort",
+            rationale: "Required content cannot be read. Investigate the referenced documents, or abort the instance if it is no longer needed."
+        } ];
+
       case "failed-effect":
         return [ {
             verb: "retry-effect",
@@ -4568,12 +4603,12 @@ function joinCacheFor(client) {
 }
 
 function isClientProjectMember(value) {
-    return invariants.isRecord(value) && typeof value.id == "string";
+    return invariants.isRecord(value) && typeof value.id == "string" && (value.isRobot === void 0 || typeof value.isRobot == "boolean");
 }
 
-async function requestProjectMembers(request, projectId) {
+async function _requestProjectMembers(request, projectId) {
     const project = await request({
-        uri: `/projects/${encodeURIComponent(projectId)}`
+        url: `/projects/${encodeURIComponent(projectId)}`
     }), members = invariants.isRecord(project) ? project.members : void 0;
     if (!Array.isArray(members) || !members.every(isClientProjectMember)) throw new Error(`Project member directory response is invalid for project "${projectId}"`);
     return members;
@@ -4581,7 +4616,7 @@ async function requestProjectMembers(request, projectId) {
 
 async function requestProjectUsers(args) {
     const {request: request, projectId: projectId, memberIds: memberIds} = args, response = await request({
-        uri: `/projects/${encodeURIComponent(projectId)}/users/${memberIds.map(encodeURIComponent).join(",")}`
+        url: `/projects/${encodeURIComponent(projectId)}/users/${memberIds.map(encodeURIComponent).join(",")}`
     }), rows = Array.isArray(response) ? response : [ response ];
     if (!rows.every(isClientProjectUser)) throw new Error(`Project user directory response is invalid for project "${projectId}"`);
     const requested = new Set(memberIds);
@@ -4589,7 +4624,7 @@ async function requestProjectUsers(args) {
 }
 
 async function requestProjectMemberDirectory(args) {
-    const {request: request, projectId: projectId} = args, members = await requestProjectMembers(request, projectId), memberIds = members.map(member => member.id).filter(id => invariants.classifyPrincipalId(id).namespace === "project");
+    const {request: request, projectId: projectId} = args, members = await _requestProjectMembers(request, projectId), memberIds = members.map(member => member.id).filter(id => invariants.classifyPrincipalId(id).namespace === "project");
     if (memberIds.length === 0) return {
         members: members,
         globalUsers: []
@@ -4664,7 +4699,7 @@ function clientProjectUserDirectory(client, projectId) {
             });
             try {
                 const response = await client.request({
-                    uri: `/projects/${encodeURIComponent(projectId)}/users/${encodeURIComponent(id)}`
+                    url: `/projects/${encodeURIComponent(projectId)}/users/${encodeURIComponent(id)}`
                 }), candidate = Array.isArray(response) ? response[0] : response;
                 return candidate == null ? {
                     status: "missing"
@@ -4776,8 +4811,30 @@ function collectWatchRefs(instance) {
 }
 
 function collectSubjectRefs(instance) {
-    const stage = invariants.findOpenStageEntry(instance), activityFields = stage?.activities.map(activity => activity.fields) ?? [];
-    return [ ...entryDocRefs(instance.fields), ...entryDocRefs(stage?.fields), ...activityFields.flatMap(entryDocRefs), ...entryReleaseRefs(instance.fields), ...entryReleaseRefs(stage?.fields), ...activityFields.flatMap(entryReleaseRefs) ];
+    const entries = activeFieldEntries(instance).map(({entry: entry}) => entry);
+    return [ ...entryDocRefs(entries), ...entryReleaseRefs(entries) ];
+}
+
+function activeFieldEntries(instance) {
+    const stage = invariants.findOpenStageEntry(instance);
+    return [ ...scopedEntries(instance.fields, {
+        scope: "workflow"
+    }), ...scopedEntries(stage?.fields, {
+        scope: "stage"
+    }), ...(stage?.activities ?? []).flatMap(activity => scopedEntries(activity.fields, {
+        scope: "activity",
+        activity: activity.name
+    })) ];
+}
+
+function scopedEntries(entries, scope) {
+    return (entries ?? []).map(entry => ({
+        target: {
+            ...scope,
+            field: entry.name
+        },
+        entry: entry
+    }));
 }
 
 function foreignSubjectRefs(instance) {
@@ -4878,6 +4935,10 @@ function entrySubjectRefs(entries) {
     return fieldEntries(entries).flatMap(entry => (typeof entry._type == "string" && invariants.isSingleDocRefKind(entry._type) || entry._type === "release.ref") && invariants.isGdr(entry.value) ? [ entry.value ] : []);
 }
 
+function missingEntryDocRefs(entries, knownIds) {
+    return entryDocRefs(entries).filter(reference => !knownIds.has(reference.id));
+}
+
 function fieldEntries(entries) {
     return Array.isArray(entries) ? entries.filter(entry => !!entry && typeof entry == "object") : [];
 }
@@ -6148,7 +6209,7 @@ async function resolveThroughDirectory(args) {
     if (safeMisses.length === 0 || client.request === void 0) return out;
     try {
         const response = await client.request({
-            uri: `/projects/${encodeURIComponent(projectId)}/users/${safeMisses.map(encodeURIComponent).join(",")}`,
+            url: `/projects/${encodeURIComponent(projectId)}/users/${safeMisses.map(encodeURIComponent).join(",")}`,
             tag: REQUEST_TAG.accessResolveActor
         });
         ingestDirectoryRows({
@@ -6348,6 +6409,12 @@ function memoizedBy(compute) {
     };
 }
 
+function chunks(values, size) {
+    return Array.from({
+        length: Math.ceil(values.length / size)
+    }, (_, index) => values.slice(index * size, (index + 1) * size));
+}
+
 async function hydrateSnapshot(args) {
     const {client: client, clientForGdr: clientForGdr, instance: instance, overlay: overlay} = args, loaded = [], visited = /* @__PURE__ */ new Set;
     loaded.push({
@@ -6458,12 +6525,6 @@ function groupReads(reads) {
     return [ ...byClient.values() ].flatMap(groups => [ ...groups.values() ]);
 }
 
-function chunks(values, size) {
-    return Array.from({
-        length: Math.ceil(values.length / size)
-    }, (_, index) => values.slice(index * size, (index + 1) * size));
-}
-
 function collectEntryDocUris(resolvedFieldEntries) {
     return entryDocRefs(resolvedFieldEntries).map(ref => ref.id);
 }
@@ -7683,6 +7744,29 @@ async function refreshStageGuards({ctx: ctx, mutation: mutation, stageName: stag
     });
 }
 
+function missingRequiredDocuments({instance: instance, definition: definition, snapshot: snapshot}) {
+    return (definition.fields ?? []).filter(field => field.required === !0 && invariants.refKindAcceptsTypes(field.type)).flatMap(field => {
+        const entry = instance.fields.find(candidate => candidate.name === field.name && candidate._type === field.type);
+        return missingEntryDocRefs(entry === void 0 ? [] : [ entry ], snapshot.knownIds).map(reference => ({
+            target: {
+                scope: "workflow",
+                field: field.name
+            },
+            reference: reference
+        }));
+    });
+}
+
+function requiredDocumentRequirements(args) {
+    return [ ...new Set(missingRequiredDocuments(args).map(({target: target}) => target.field)) ].map(field => {
+        const title = args.definition.fields?.find(entry => entry.name === field)?.title ?? field;
+        return {
+            name: `field:${field}`,
+            title: `Documents selected for “${title}” must be readable`
+        };
+    });
+}
+
 async function discoverItems(args) {
     const {client: client, groq: groq, params: params, perspective: perspective} = args;
     return client.fetch(groq, paramsForLake(params), {
@@ -8259,7 +8343,7 @@ async function persistStageMove({ctx: ctx, mutation: mutation, exitedStage: exit
 }
 
 async function pickTransition(ctx, stage) {
-    for (const candidate of stage.transitions ?? []) {
+    if (!(missingRequiredDocuments(ctx).length > 0)) for (const candidate of stage.transitions ?? []) {
         const outcome = await ctxEvaluateConditionOutcome({
             ctx: ctx,
             condition: candidate.when
@@ -8361,7 +8445,7 @@ const actorCache = /* @__PURE__ */ new WeakMap, grantsCache = /* @__PURE__ */ ne
 
 async function resolveAccess(taggedClient, args = {}) {
     const client = unwrapRequestTag(taggedClient), requestFn = lazyRequest(client);
-    if (requestFn === void 0) throw new invariants.ContractViolationError("workflow: no actor available. The engine resolves the actor from the client's token via `client.request({ uri: '/users/me' })`. Supply a real `@sanity/client` configured with a token (the test bench serves these endpoints per registered token).");
+    if (requestFn === void 0) throw new invariants.ContractViolationError("workflow: no actor available. The engine resolves the actor from the client's token via `client.request({url: '/users/me'})`. Supply a real `@sanity/client` configured with a token (the test bench serves these endpoints per registered token).");
     const grantsPromise = args.grantsFromPath !== void 0 ? cachedGrants({
         client: client,
         requestFn: requestFn,
@@ -8430,20 +8514,32 @@ function cachedByKey(args) {
 }
 
 async function fetchActor(client, requestFn) {
-    const [resourceUser, globalUser] = await Promise.all([ fetchCurrentUser(requestFn, "the workflow resource host"), fetchGlobalUser(client) ]), resourceId = usableId(resourceUser), globalHostId = usableId(globalUser.user), carriedId = invariants.firstCarriedGlobalId([ globalHostId, resourceId ]), sessionId = carriedId ?? globalHostId ?? resourceId;
+    const resourceUser = await fetchCurrentUser(requestFn, "the workflow resource host"), resourceId = usableId(resourceUser), resourceGlobalId = invariants.firstCarriedGlobalId([ resourceId ]) ?? invariants.directoryBridgeId(resourceUser?.sanityUserId);
+    if (resourceGlobalId !== void 0) return identityFromUsers({
+        id: resourceGlobalId,
+        resourceUser: resourceUser
+    });
+    const globalUser = await fetchGlobalUser(client), globalHostId = usableId(globalUser.user), carriedId = invariants.firstCarriedGlobalId([ globalHostId ]), sessionId = carriedId ?? globalHostId ?? resourceId;
     if (sessionId === void 0) return;
     const bridge = carriedId === void 0 ? await bridgeProjectPrincipal({
         client: client,
         sessionId: sessionId,
         resourceId: resourceId
     }) : NO_BRIDGE, id = bridge.status === "resolved" ? bridge.globalId : sessionId;
-    refuseProjectScopedActor({
+    return refuseProjectScopedActor({
         id: id,
         globalUser: globalUser,
         globalHostId: globalHostId,
         bridgeFailure: bridge.status === "unavailable" ? bridge : void 0
+    }), identityFromUsers({
+        id: id,
+        resourceUser: resourceUser,
+        globalUser: globalUser.user
     });
-    const roleNames = roleNamesFor(resourceUser, globalUser);
+}
+
+function identityFromUsers(args) {
+    const {id: id, resourceUser: resourceUser, globalUser: globalUser} = args, resourceId = usableId(resourceUser), roleNames = roleNamesFor(resourceUser, globalUser);
     return {
         actor: {
             kind: "person",
@@ -8459,7 +8555,7 @@ async function fetchActor(client, requestFn) {
 }
 
 function roleNamesFor(resourceUser, globalUser) {
-    return (resourceUser?.roles?.length ? resourceUser : globalUser.user)?.roles?.map(r => r.name).filter(n => !!n) ?? [];
+    return (resourceUser?.roles?.length ? resourceUser : globalUser)?.roles?.map(r => r.name).filter(n => !!n) ?? [];
 }
 
 const NO_BRIDGE = {
@@ -8523,11 +8619,11 @@ function usableId(user) {
 async function fetchCurrentUser(requestFn, hostDescription) {
     try {
         return await requestFn({
-            uri: "/users/me",
+            url: "/users/me",
             tag: REQUEST_TAG.accessResolveActor
         });
     } catch (err) {
-        throw new Error(`workflow: /users/me request against ${hostDescription} failed. The engine resolves the actor from the client's token via \`client.request({ uri: '/users/me' })\`. Check the token/connectivity.`, {
+        throw new Error(`workflow: /users/me request against ${hostDescription} failed. The engine resolves the actor from the client's token via \`client.request({url: '/users/me'})\`. Check the token/connectivity.`, {
             cause: err
         });
     }
@@ -8544,7 +8640,7 @@ async function fetchGlobalUser(client) {
     };
     try {
         const user = await sibling.request({
-            uri: "/users/me",
+            url: "/users/me",
             tag: REQUEST_TAG.accessResolveActor
         }), id = usableId(user);
         return sibling.requireGlobalPrincipal && id !== void 0 && invariants.classifyPrincipalId(id).namespace === "project" ? {
@@ -8667,7 +8763,7 @@ async function resolveOrganizationId(args) {
         load: async () => {
             try {
                 const project = await requestFn({
-                    uri: `/projects/${encodeURIComponent(projectId)}`,
+                    url: `/projects/${encodeURIComponent(projectId)}`,
                     tag: REQUEST_TAG.accessResolveOrg
                 });
                 if (!invariants.isRecord(project)) return;
@@ -8692,15 +8788,17 @@ function httpStatusOf(err) {
     return typeof status == "number" ? status : void 0;
 }
 
+function attributesRequestOf(client) {
+    const version = client.config?.().apiVersion, request = typeof client.withConfig == "function" || version === void 0 || version === ENGINE_API_VERSION ? lazyRequest(pinApiVersion(client)) : void 0;
+    return request === void 0 && console.warn("workflow: skipped org attributes fetch; the client cannot issue API-version-pinned requests. Advisory $attributes stays undefined (conditions referencing it fail closed)."), 
+    request;
+}
+
 async function fetchAttributesCached(args) {
-    const {client: client, orgId: orgId} = args, sibling = globalHostRequestOf(client);
-    if ("reason" in sibling) {
-        console.warn(`workflow: skipped org attributes fetch (${sibling.reason}); advisory $attributes stays undefined (conditions referencing it fail closed).`);
-        return;
-    }
-    try {
-        const response = await sibling.request({
-            uri: `/organizations/${encodeURIComponent(orgId)}/users/me/attributes?limit=${ATTRIBUTES_FETCH_LIMIT}`,
+    const {client: client, orgId: orgId} = args, request = attributesRequestOf(client);
+    if (request !== void 0) try {
+        const response = await request({
+            url: `/organizations/${encodeURIComponent(orgId)}/users/me/attributes?limit=${ATTRIBUTES_FETCH_LIMIT}`,
             tag: REQUEST_TAG.accessAttributes
         }), envelope = invariants.isRecord(response) ? response : void 0;
         if (envelope?.hasMore === !0) {
@@ -8814,6 +8912,15 @@ async function resolveActionCommit({ctx: ctx, activityName: activityName, action
         actionName: actionName,
         status: entry?.status
     });
+    const unmetRequirements = requiredDocumentRequirements(ctx);
+    if (unmetRequirements.length > 0) throw new ActionDisabledError({
+        activity: activityName,
+        action: actionName,
+        reason: {
+            kind: "requirements-unmet",
+            unmetRequirements: unmetRequirements
+        }
+    });
     const params = validateActionParams({
         action: action,
         activityName: activityName,
@@ -8970,13 +9077,13 @@ async function runTriggeredActions({ctx: ctx, mutation: mutation, stage: stage})
 async function runActivityTriggers({ctx: ctx, mutation: mutation, activity: activity}) {
     let fires = 0, ranFieldOps = !1;
     for (const action of activity.actions ?? []) {
-        if (!invariants.isCascadeFired(action)) continue;
         const entry = currentActivities(mutation).find(e => e.name === activity.name);
         if (entry === void 0 || entry.status !== "active") break;
-        if ((entry.firedActions ?? []).includes(action.name) || !await triggerIsLive({
+        if (!await triggerIsLive({
             ctx: ctx,
             activity: activity,
-            action: action
+            action: action,
+            entry: entry
         })) continue;
         const result = await fireTriggeredAction({
             ctx: ctx,
@@ -8993,8 +9100,12 @@ async function runActivityTriggers({ctx: ctx, mutation: mutation, activity: acti
     };
 }
 
-async function triggerIsLive({ctx: ctx, activity: activity, action: action}) {
-    if (!tokenMayExecute({
+function isUnfiredTrigger(action, entry) {
+    return invariants.isCascadeFired(action) && !(entry.firedActions ?? []).includes(action.name);
+}
+
+async function triggerIsLive({ctx: ctx, activity: activity, action: action, entry: entry}) {
+    if (!isUnfiredTrigger(action, entry) || missingRequiredDocuments(ctx).length > 0 || !tokenMayExecute({
         actor: ctx.actor,
         action: action,
         ctx: ctx
@@ -10098,7 +10209,7 @@ function staleClaimReason(args) {
     if (isClaimExpired(claim, args.now)) return "lease-expired";
 }
 
-function renewClaimLease(args) {
+function renewClaimLease$1(args) {
     const {mutation: mutation, effectKey: effectKey, now: now, leaseMs: leaseMs} = args;
     mutation.pendingEffects = mutation.pendingEffects.map(entry => entry._key === effectKey && entry.claim !== void 0 ? {
         ...entry,
@@ -10135,7 +10246,7 @@ async function commitReport({ctx: ctx, effectKey: effectKey, claimToken: claimTo
         mutation: mutation,
         record: requestRecord,
         now: ctx.now
-    }), renewClaimLease({
+    }), renewClaimLease$1({
         mutation: mutation,
         effectKey: effectKey,
         now: ctx.now,
@@ -10224,6 +10335,100 @@ async function commitResetActivity({ctx: ctx, activity: activity, to: to, reques
     };
 }
 
+const AvailabilityResponse = v__namespace.object({
+    documents: v__namespace.array(v__namespace.object({
+        _id: v__namespace.string()
+    })),
+    omitted: v__namespace.array(v__namespace.object({
+        id: v__namespace.string(),
+        reason: v__namespace.picklist([ "existence", "permission" ])
+    }))
+}), AVAILABILITY_BATCH_SIZE = 100, AVAILABILITY_CONCURRENCY = 4, pendingReads = /* @__PURE__ */ new WeakMap;
+
+function groupsFor(documents, clientForGdr) {
+    const groups = /* @__PURE__ */ new Map;
+    for (const {reference: reference} of documents) {
+        const parsed = invariants.parseGdr(reference.id), resource = invariants.resourceFromParsed(parsed), key = invariants.resourceGdr(resource), group = groups.get(key) ?? {
+            client: clientForGdr(parsed),
+            resource: resource,
+            documents: /* @__PURE__ */ new Map
+        };
+        group.documents.set(reference.id, parsed.documentId), groups.set(key, group);
+    }
+    return [ ...groups.values() ];
+}
+
+async function readGroup(group) {
+    let response;
+    try {
+        const url = documentUrl(group);
+        url !== void 0 && group.client.request !== void 0 ? response = await readResponse(group.client, url) : logUnavailable({
+            resource: group.resource,
+            reason: "unsupported-client"
+        });
+    } catch (error) {
+        logUnavailable({
+            resource: group.resource,
+            reason: v__namespace.isValiError(error) ? "invalid-response" : "request-failed",
+            error: error
+        });
+    }
+    return [ ...group.documents ].map(([uri, id]) => [ uri, availabilityOf(response, id) ]);
+}
+
+function logUnavailable({resource: resource, reason: reason, error: error}) {
+    const statusCode = typeof error == "object" && error !== null && "statusCode" in error ? error.statusCode : void 0;
+    console.warn("[workflows] Document availability could not be confirmed.", {
+        resource: invariants.resourceGdr(resource),
+        reason: reason,
+        ...typeof statusCode == "number" ? {
+            statusCode: statusCode
+        } : {}
+    });
+}
+
+function availabilityOf(response, id) {
+    if (response === void 0) return "unreadable";
+    const omissions = response.omitted.filter(entry => idUtils.getPublishedId(idUtils.DocumentId(entry.id)) === id);
+    return omissions.some(entry => entry.reason === "permission") ? "unreadable" : response.documents.some(doc => idUtils.getPublishedId(idUtils.DocumentId(doc._id)) === id) ? "outside-perspective" : omissions.some(entry => entry.id === id && entry.reason === "existence") ? "deleted" : "unreadable";
+}
+
+function documentUrl(group) {
+    const ids = [ ...new Set(group.documents.values()) ].sort().map(encodeURIComponent).join(",");
+    let url;
+    if ("getDataUrl" in group.client && group.client.getDataUrl !== void 0) url = group.client.getDataUrl("doc", ids); else {
+        if (group.resource.type !== "dataset") return;
+        const {dataset: dataset} = invariants.datasetResourceParts(group.resource.id);
+        url = `/data/doc/${dataset}/${ids}`;
+    }
+    return `${url}?includeAllVersions=true`;
+}
+
+function readResponse(client, url) {
+    const identity = unwrapRequestTag(client), pending = pendingReads.get(identity) ?? /* @__PURE__ */ new Map;
+    pendingReads.set(identity, pending);
+    const existing = pending.get(url);
+    if (existing !== void 0) return existing;
+    const result = client.request({
+        url: url
+    }).then(response => v__namespace.parse(AvailabilityResponse, response)).finally(() => pending.delete(url));
+    return pending.set(url, result), result;
+}
+
+function documentAvailabilityReader(args) {
+    return async documents => {
+        const result = /* @__PURE__ */ new Map, groups = groupsFor(documents, args.clientForGdr).flatMap(group => chunks([ ...group.documents ], AVAILABILITY_BATCH_SIZE).map(entries => ({
+            ...group,
+            documents: new Map(entries)
+        })));
+        for (const wave of chunks(groups, AVAILABILITY_CONCURRENCY)) {
+            const rows = await Promise.all(wave.map(readGroup));
+            for (const [uri, availability] of rows.flat()) result.set(uri, availability);
+        }
+        return result;
+    };
+}
+
 const REPLAY_SURFACE = {
     allows: () => !0,
     description: "any resource (in-memory replay; the committing surface enforces)"
@@ -10375,6 +10580,80 @@ function fabricatable(assignment) {
     return assignment.target.path.every(segment => typeof segment != "number" || segment <= groqConditionDescribe.MAX_COUNTERFACTUAL_INDEX);
 }
 
+function missingDocumentsOf({instance: instance, snapshot: snapshot, definition: definition}) {
+    const stage = findStageNode({
+        definition: definition,
+        stageName: instance.currentStage
+    });
+    return activeFieldEntries(instance).flatMap(({target: target, entry: entry}) => {
+        const declarations = {
+            workflow: definition?.fields,
+            stage: stage?.fields,
+            activity: stage?.activities?.find(activity => activity.name === target.activity)?.fields
+        }, title = entry.title ?? declarations[target.scope ?? "workflow"]?.find(field => field.name === target.field)?.title;
+        return missingEntryDocRefs([ entry ], snapshot.knownIds).map(reference => ({
+            target: target,
+            reference: reference,
+            ...title !== void 0 ? {
+                title: title
+            } : {}
+        }));
+    });
+}
+
+function blockingConditions(evaluation) {
+    const transitions = evaluation.currentStage.transitions.some(entry => entry.whenSatisfied) ? [] : evaluation.currentStage.transitions;
+    return [ ...evaluation.currentStage.activities.filter(entry => entry.status === "active" && (entry.activity.actions ?? []).length > 0).flatMap(entry => (entry.unmetRequirements ?? []).map(requirement => ({
+        insight: entry.requirementInsights?.[requirement.name],
+        activity: entry.activity.name
+    }))), ...transitions.map(entry => ({
+        insight: entry.insight
+    })) ];
+}
+
+function readsDocumentContent({entry: entry, read: read, atom: atom}) {
+    return groqConditionDescribe.atomReadsDataset(atom) ? !0 : invariants.isSingleDocRefKind(entry._type) && read.path.length > 1 && read.path[1] !== "_id" && read.path[1] !== "_type";
+}
+
+function contentTargets({atoms: atoms, fields: fields, activity: activity}) {
+    return atoms.flatMap(atom => atom.reads.flatMap(read => {
+        if (read.variable !== "fields") return [];
+        const field = fields.findLast(({entry: entry, target: target}) => entry.name === read.path[0] && (target.scope !== "activity" || target.activity === activity));
+        return field !== void 0 && readsDocumentContent({
+            entry: field.entry,
+            read: read,
+            atom: atom
+        }) ? [ _fieldTargetLabel(field.target) ] : [];
+    }));
+}
+
+async function blockingAtoms(condition, args) {
+    const atoms = condition.insight?.blockedBy.map(({atom: atom}) => atom) ?? [], names = [ ...new Set(atoms.flatMap(atom => atom.reads).filter(read => read.path.length === 0 && args.definition.predicates?.[read.variable] !== void 0).map(read => read.variable)) ];
+    if (names.length === 0) return atoms;
+    const site = args.sites.find(entry => entry.insight === condition.insight);
+    if (site === void 0) throw new Error("Missing evaluated scope for a blocking condition");
+    const dependencies = await Promise.all(names.map(async name => {
+        const predicate = args.definition.predicates?.[name];
+        if (predicate === void 0) throw new Error(`Missing predicate "${name}"`);
+        return (await groqConditionDescribe.explainCondition({
+            condition: site.params[name] === !0 ? `!(${predicate})` : predicate,
+            dataset: args.snapshot.docs,
+            params: site.params
+        })).blockedBy.map(({atom: atom}) => atom);
+    }));
+    return [ ...atoms, ...dependencies.flat() ];
+}
+
+async function blockingMissingDocuments(args) {
+    if (!args.missingDocuments?.length) return [];
+    const fields = activeFieldEntries(args.instance), targets = (await Promise.all(blockingConditions(args).map(async condition => contentTargets({
+        atoms: await blockingAtoms(condition, args),
+        fields: fields,
+        activity: condition.activity
+    })))).flat(), blocked = /* @__PURE__ */ new Set([ ...targets, ...missingRequiredDocuments(args).map(({target: target}) => _fieldTargetLabel(target)) ]);
+    return args.missingDocuments.filter(({target: target}) => blocked.has(_fieldTargetLabel(target)));
+}
+
 async function subjectResourceGrants(args) {
     const {clientForGdr: clientForGdr, instance: instance} = args, clients = /* @__PURE__ */ new Map;
     for (const {parsed: parsed, resource: resource} of foreignSubjectRefs(instance)) {
@@ -10437,6 +10716,9 @@ async function evaluateInstance(args) {
         guards: guards,
         now: now,
         resourceGrants: resourceGrants,
+        documentAvailability: documentAvailabilityReader({
+            clientForGdr: clientForGdr
+        }),
         guardDereference: clientGuardDereference(client),
         ...localPrincipalId !== void 0 ? {
             localPrincipalId: localPrincipalId
@@ -10544,7 +10826,11 @@ async function evaluateFromSnapshot(args) {
     }), subjectPermissionReason = subjectDenials.length > 0 ? {
         kind: "subject-permission-denied",
         denied: subjectDenials
-    } : void 0, sites = [], activityEvaluations = [];
+    } : void 0, sites = [], activityEvaluations = [], requiredDocuments = requiredDocumentRequirements({
+        instance: instance,
+        definition: definition,
+        snapshot: snapshot
+    });
     for (const activity of stage.activities ?? []) activityEvaluations.push(await evaluateActivity({
         activity: activity,
         statusEntry: currentActivityEntries.find(t => t.name === activity.name),
@@ -10555,36 +10841,23 @@ async function evaluateFromSnapshot(args) {
         stageHasExits: !isTerminalStage(stage),
         guardDenial: guardDenial,
         subjectPermissionReason: subjectPermissionReason,
+        requiredDocuments: requiredDocuments,
         sites: sites,
         autonomy: activityAutonomyOf(stageAutonomy2, activity.name),
         fireConsequence: fireConsequence
     }));
-    const cascadeParams = await renderConditionScope(scopeSource), transitionEvaluations = [];
-    for (const transition of stage.transitions ?? []) {
-        const insight = await explainSite({
-            site: {
-                kind: "transition",
-                transition: transition.name
-            },
-            condition: transition.when,
-            params: cascadeParams,
-            snapshot: snapshot,
-            sites: sites
-        });
-        transitionEvaluations.push({
-            transition: transition,
-            whenSatisfied: insight.outcome === "satisfied",
-            unevaluable: insight.outcome === "unevaluable",
-            insight: insight
-        });
-    }
-    const currentStage = {
+    const cascadeParams = await renderConditionScope(scopeSource), transitionEvaluations = await evaluateTransitions({
+        stage: stage,
+        cascadeParams: cascadeParams,
+        snapshot: snapshot,
+        sites: sites
+    }), currentStage = {
         stage: stage,
         ...semanticsOf(stage),
         activities: activityEvaluations,
         transitions: transitionEvaluations,
         autonomy: stageAutonomy2
-    }, pendingOnYou = activityEvaluations.filter(t => t.pendingOnActor), canInteract = activityEvaluations.some(t => t.actions.some(a => a.allowed)), editGuardDenial = guardDenial?.kind === "mutation-guard-denied" ? guardDenial : void 0, editableFields = await evaluateEditableFields({
+    }, missingDocuments = await readMissingDocuments(args), pendingOnYou = activityEvaluations.filter(t => t.pendingOnActor), canInteract = activityEvaluations.some(t => t.actions.some(a => a.allowed)), editGuardDenial = guardDenial?.kind === "mutation-guard-denied" ? guardDenial : void 0, editableFields = await evaluateEditableFields({
         instance: instance,
         definition: definition,
         stage: stage,
@@ -10611,6 +10884,17 @@ async function evaluateFromSnapshot(args) {
             sites: sites,
             snapshot: snapshot
         }),
+        ...missingDocuments.length > 0 ? {
+            missingDocuments: missingDocuments,
+            blockingMissingDocuments: await blockingMissingDocuments({
+                instance: instance,
+                definition: definition,
+                currentStage: currentStage,
+                missingDocuments: missingDocuments,
+                snapshot: snapshot,
+                sites: sites
+            })
+        } : {},
         autonomy: autonomy,
         ...nextEvaluationAt !== void 0 ? {
             nextEvaluationAt: nextEvaluationAt
@@ -10618,6 +10902,42 @@ async function evaluateFromSnapshot(args) {
     };
 }
 
+async function readMissingDocuments(args) {
+    const missingDocuments = missingDocumentsOf(args);
+    if (args.documentAvailability === void 0 || missingDocuments.length === 0) return missingDocuments;
+    const availability = await args.documentAvailability(missingDocuments);
+    return missingDocuments.map(document => {
+        const verdict = availability.get(document.reference.id);
+        return verdict === void 0 ? document : {
+            ...document,
+            availability: verdict
+        };
+    });
+}
+
+async function evaluateTransitions(args) {
+    const {stage: stage, cascadeParams: cascadeParams, snapshot: snapshot, sites: sites} = args, evaluations = [];
+    for (const transition of stage.transitions ?? []) {
+        const insight = await explainSite({
+            site: {
+                kind: "transition",
+                transition: transition.name
+            },
+            condition: transition.when,
+            params: cascadeParams,
+            snapshot: snapshot,
+            sites: sites
+        });
+        evaluations.push({
+            transition: transition,
+            whenSatisfied: insight.outcome === "satisfied",
+            unevaluable: insight.outcome === "unevaluable",
+            insight: insight
+        });
+    }
+    return evaluations;
+}
+
 const AUTONOMY_CACHE = /* @__PURE__ */ new WeakMap;
 
 function autonomyOf(definition) {
@@ -10628,54 +10948,56 @@ function autonomyOf(definition) {
 }
 
 async function evaluateEditableFields(args) {
-    const {instance: instance, definition: definition, stage: stage, snapshot: snapshot, scope: scope, scopeForActivity: scopeForActivity, guardDenial: guardDenial, sites: sites} = args, fields = [];
-    for (const site of editableFieldsInStage(definition, stage)) {
-        const window = fieldWindowOpen(instance, site), insight = await editPredicateInsight({
-            site: site,
-            snapshot: snapshot,
-            scope: scope,
-            scopeForActivity: scopeForActivity,
-            sites: sites
-        }), predicateSatisfied = insight === void 0 || insight.outcome === "satisfied", reason = editDisabledReason({
-            effective: site.effective,
-            instance: instance,
-            window: window,
-            guardDenial: guardDenial,
-            predicateSatisfied: predicateSatisfied
-        }), value = readFieldValue(instance, site);
-        fields.push({
-            scope: site.scope,
-            ...site.activity !== void 0 ? {
-                activity: site.activity
-            } : {},
-            name: site.name,
-            type: site.type,
-            ...site.title !== void 0 ? {
-                title: site.title
-            } : {},
-            ...site.validation !== void 0 ? {
-                validation: site.validation
-            } : {},
-            ...site.roles !== void 0 ? {
-                roles: site.roles,
-                ...definition.roleAliases !== void 0 ? {
-                    roleAliases: definition.roleAliases
-                } : {}
-            } : {},
-            value: value,
-            editable: reason === void 0,
-            ...reason !== void 0 ? {
-                disabledReason: reason
-            } : {},
-            ...fieldProvenance(instance, site.ref),
-            ...insight !== void 0 ? {
-                insight: insight
-            } : {}
-        });
-    }
+    const fields = [];
+    for (const site of editableFieldsInStage(args.definition, args.stage)) fields.push(await evaluateEditableField(args, site));
     return fields;
 }
 
+async function evaluateEditableField(args, site) {
+    const {instance: instance, definition: definition, snapshot: snapshot, scope: scope, scopeForActivity: scopeForActivity, guardDenial: guardDenial, sites: sites} = args, window = fieldWindowOpen(instance, site), insight = await editPredicateInsight({
+        site: site,
+        snapshot: snapshot,
+        scope: scope,
+        scopeForActivity: scopeForActivity,
+        sites: sites
+    }), predicateSatisfied = insight === void 0 || insight.outcome === "satisfied", reason = editDisabledReason({
+        effective: site.effective,
+        instance: instance,
+        window: window,
+        guardDenial: guardDenial,
+        predicateSatisfied: predicateSatisfied
+    });
+    return {
+        scope: site.scope,
+        ...site.activity !== void 0 ? {
+            activity: site.activity
+        } : {},
+        name: site.name,
+        type: site.type,
+        ...site.title !== void 0 ? {
+            title: site.title
+        } : {},
+        ...site.validation !== void 0 ? {
+            validation: site.validation
+        } : {},
+        ...site.roles !== void 0 ? {
+            roles: site.roles,
+            ...definition.roleAliases !== void 0 ? {
+                roleAliases: definition.roleAliases
+            } : {}
+        } : {},
+        value: readFieldValue(instance, site),
+        editable: reason === void 0,
+        ...reason !== void 0 ? {
+            disabledReason: reason
+        } : {},
+        ...fieldProvenance(instance, site.ref),
+        ...insight !== void 0 ? {
+            insight: insight
+        } : {}
+    };
+}
+
 async function editPredicateInsight(args) {
     const {site: site, snapshot: snapshot, scope: scope, scopeForActivity: scopeForActivity, sites: sites} = args;
     if (typeof site.effective != "string") return;
@@ -10699,14 +11021,10 @@ async function editPredicateInsight(args) {
 async function forecastSubjectDenials(args) {
     const {instance: instance, snapshot: snapshot, resourceGrants: resourceGrants} = args;
     if (resourceGrants === void 0 || resourceGrants.size === 0) return [];
-    const denials = [], seen = /* @__PURE__ */ new Set;
-    for (const {ref: ref, parsed: parsed, resource: resource} of foreignSubjectRefs(instance)) {
-        if (seen.has(ref.id)) continue;
-        seen.add(ref.id);
-        const access = resourceGrants.get(invariants.resourceGdr(resource));
-        if (access === void 0) continue;
-        const doc = snapshot.docs.find(d => d._id === ref.id);
-        doc !== void 0 && await subjectUpdateAllowed({
+    const denials = [], subjects = new Map(foreignSubjectRefs(instance).map(subject => [ subject.ref.id, subject ]));
+    for (const {ref: ref, parsed: parsed, resource: resource} of subjects.values()) {
+        const access = resourceGrants.get(invariants.resourceGdr(resource)), doc = snapshot.docs.find(d => d._id === ref.id);
+        access === void 0 || doc === void 0 || await subjectUpdateAllowed({
             doc: doc,
             parsed: parsed,
             grants: access.grants,
@@ -10739,13 +11057,13 @@ async function subjectUpdateAllowed(args) {
 }
 
 async function evaluateActivity(args) {
-    const {activity: activity, statusEntry: statusEntry, instance: instance, snapshot: snapshot, activityScope: activityScope, cascadeActivityScope: cascadeActivityScope, stageHasExits: stageHasExits, guardDenial: guardDenial, subjectPermissionReason: subjectPermissionReason, sites: sites, autonomy: autonomy, fireConsequence: fireConsequence} = args, status = statusEntry?.status ?? "skipped", assigned = activityScope.assigned === !0, {unmetRequirements: unmetRequirements, ...conditionInsights} = await explainActivityConditions({
+    const {activity: activity, statusEntry: statusEntry, instance: instance, snapshot: snapshot, activityScope: activityScope, cascadeActivityScope: cascadeActivityScope, stageHasExits: stageHasExits, guardDenial: guardDenial, subjectPermissionReason: subjectPermissionReason, requiredDocuments: requiredDocuments, sites: sites, autonomy: autonomy, fireConsequence: fireConsequence} = args, status = statusEntry?.status ?? "skipped", assigned = activityScope.assigned === !0, {unmetRequirements: activityRequirements, ...conditionInsights} = await explainActivityConditions({
         activity: activity,
         activityScope: activityScope,
         cascadeActivityScope: cascadeActivityScope,
         snapshot: snapshot,
         sites: sites
-    }), requirementsReason = unmetRequirements.length > 0 ? {
+    }), unmetRequirements = [ ...requiredDocuments, ...activityRequirements ], requirementsReason = unmetRequirements.length > 0 ? {
         kind: "requirements-unmet",
         unmetRequirements: unmetRequirements
     } : void 0, actions = [];
@@ -11121,6 +11439,46 @@ function claimReleasedEntry(args) {
     };
 }
 
+const RENEW_MAX_ATTEMPTS = 3;
+
+async function claimOf(args) {
+    const {client: client, tag: tag, instanceId: instanceId, effectKey: effectKey} = args, instance = await reload({
+        client: client,
+        instanceId: instanceId,
+        tag: tag
+    });
+    return {
+        instance: instance,
+        claim: instance.pendingEffects.find(e => e._key === effectKey)?.claim
+    };
+}
+
+async function claimStillHeld(args) {
+    const {claimToken: claimToken, ...where} = args, {claim: claim} = await claimOf(where);
+    return claim?.claimToken === claimToken;
+}
+
+async function renewClaimLease(args) {
+    const {client: client, tag: tag, instanceId: instanceId, effectKey: effectKey, claimToken: claimToken, holdMs: holdMs, clock: clock} = args;
+    for (let attempt = 1; attempt <= RENEW_MAX_ATTEMPTS; attempt++) {
+        const {instance: instance, claim: claim} = await claimOf({
+            client: client,
+            tag: tag,
+            instanceId: instanceId,
+            effectKey: effectKey
+        });
+        if (claim?.claimToken !== claimToken) return;
+        const until = addMs(clock(), holdMs);
+        try {
+            return await client.patch(instance._id).ifRevisionId(instance._rev).set({
+                [`pendingEffects[_key=="${effectKey}"].claim.leaseExpiresAt`]: until
+            }).commit(SYNC_COMMIT), until;
+        } catch (error) {
+            if (!isRevisionConflict(error)) throw error;
+        }
+    }
+}
+
 const SWEEP_MAX_ATTEMPTS = 5;
 
 async function sweepStaleClaims(args) {
@@ -11168,7 +11526,7 @@ function isProjectRole(value) {
 
 async function projectRoleNames(request, projectId) {
     const result = await request({
-        uri: `/projects/${encodeURIComponent(projectId)}/roles`
+        url: `/projects/${encodeURIComponent(projectId)}/roles`
     });
     if (!Array.isArray(result) || !result.every(isProjectRole)) throw new Error(`Project role catalog response is invalid for project "${projectId}"`);
     return new Set(result.map(role => role.name));
@@ -11364,7 +11722,7 @@ async function validateDefinitionRoles(args) {
     const references = args.definitions.flatMap(definitionRoleReferences);
     if (references.length === 0) /* @__PURE__ */ return new Map;
     if (args.client.request === void 0) throw new Error("workflow.deployDefinitions: definitions reference project roles, but the client cannot read the project role catalog");
-    const projectId = roleCatalogProjectId(args.client, args.workflowResource), [known, members] = await Promise.all([ projectRoleNames(args.client.request, projectId), requestProjectMembers(args.client.request, projectId) ]), unknown = references.filter(reference => !known.has(reference.role));
+    const projectId = roleCatalogProjectId(args.client, args.workflowResource), [known, members] = await Promise.all([ projectRoleNames(args.client.request, projectId), _requestProjectMembers(args.client.request, projectId) ]), unknown = references.filter(reference => !known.has(reference.role));
     if (unknown.length > 0) {
         const lines = unknown.map(({definition: definition, path: path, role: role}) => `  - ${definition}: ${path} references unknown role "${role}"`);
         throw new Error(`workflow.deployDefinitions: unknown project roles for project "${projectId}":\n${lines.join(`\n`)}`);
@@ -11494,7 +11852,7 @@ function refsOf(def) {
 }
 
 function hashDefinitionContent(def) {
-    const canonical = stableStringify(def);
+    const canonical = stableStringify(withoutAuthoringRuntime(def));
     let hash = 0xcbf29ce484222325n;
     for (let i = 0; i < canonical.length; i++) hash ^= BigInt(canonical.charCodeAt(i)), 
     hash = hash * 0x100000001b3n & 0xffffffffffffffffn;
@@ -11507,7 +11865,7 @@ function planDefinitionDeploy({def: def, latest: latest, target: target}) {
         definition: def,
         workflowResource: target.workflowResource
     });
-    const expanded = expandResourceAliases(def, target.resourceAliases), contentHash = hashDefinitionContent(expanded), unchanged = latest !== void 0 && latest.contentHash === contentHash, version = unchanged ? latest.version : (latest?.version ?? 0) + 1, docId = invariants.definitionDocId({
+    const expanded = withoutAuthoringRuntime(expandResourceAliases(def, target.resourceAliases)), contentHash = hashDefinitionContent(expanded), unchanged = latest !== void 0 && latest.contentHash === contentHash, version = unchanged ? latest.version : (latest?.version ?? 0) + 1, docId = invariants.definitionDocId({
         tag: target.tag,
         definition: expanded.name,
         version: version
@@ -11564,10 +11922,17 @@ function isDocumentEnvelopeKey(key) {
     return key.startsWith("_") || DEPLOY_STAMPED_KEYS.has(key);
 }
 
+const AUTHORING_RUNTIME_KEY = "runtime";
+
+function withoutAuthoringRuntime(def) {
+    const content = Object.entries(def).filter(([key]) => key !== AUTHORING_RUNTIME_KEY);
+    return Object.fromEntries(content);
+}
+
 function parseDefinitionInput(def, caller) {
     const label = invariants.labelFor(caller, def);
     if (def._type !== void 0 && def._type !== invariants.WORKFLOW_DEFINITION_TYPE) throw new Error(`${label}: expected a workflow definition or a "${invariants.WORKFLOW_DEFINITION_TYPE}" document, got _type "${String(def._type)}"`);
-    const content = Object.fromEntries(Object.entries(def).filter(([key]) => !isDocumentEnvelopeKey(key)));
+    const content = Object.fromEntries(Object.entries(withoutAuthoringRuntime(def)).filter(([key]) => !isDocumentEnvelopeKey(key)));
     return invariants.parseStoredDefinition(content, label);
 }
 
@@ -13487,7 +13852,7 @@ function pendingEntry(args) {
 }
 
 function createEffectCommitQueue(args) {
-    const {effectKey: effectKey, claimToken: claimToken, commit: commit} = args, pending = [];
+    const {effectKey: effectKey, claimToken: claimToken, attempt: attempt, commit: commit} = args, pending = [];
     let admitted = 0, dead, closed = !1, tail = Promise.resolve();
     function assertOpen() {
         if (dead !== void 0) throw dead;
@@ -13542,7 +13907,7 @@ function createEffectCommitQueue(args) {
                         value: entry.latestValue
                     }
                 } ],
-                idempotencyKey: `effect:${effectKey}:${claimToken}:progress:${coalesceKey}:${admitted}`,
+                idempotencyKey: `effect:${effectKey}:${claimToken}:${attempt}:progress:${coalesceKey}:${admitted}`,
                 coalesceKey: coalesceKey,
                 latestValue: value
             });
@@ -13552,6 +13917,29 @@ function createEffectCommitQueue(args) {
     };
 }
 
+function effectRetryPolicy(definition, effectName) {
+    return findEffect(definition, effectName)?.retry;
+}
+
+function retryWindowClosed(policy, elapsedMs) {
+    return policy.expiryMs !== void 0 && elapsedMs >= policy.expiryMs;
+}
+
+function nextRetryDelayMs(policy, at) {
+    if (at.attempt >= policy.attempts) return;
+    const delay = invariants.effectBackoffMs(policy, at.attempt);
+    return retryWindowClosed(policy, at.elapsedMs + delay) ? void 0 : delay;
+}
+
+function retryFailedDetail(args) {
+    const window = args.windowClosed ? ", retry window expired" : "";
+    return `failed after ${args.at.attempt} of ${args.attempts} attempts${window}: ${args.error.message}`;
+}
+
+function retrySucceededDetail(args) {
+    if (args.at.attempt !== 1) return `succeeded on attempt ${args.at.attempt} of ${args.attempts}`;
+}
+
 class MissingHandlerError extends invariants.WorkflowError {
     info;
     constructor(args) {
@@ -13634,7 +14022,7 @@ function isCancelledCompletion(data) {
 }
 
 async function drainEffectsInternal(args) {
-    const {tag: tag, workflowResource: workflowResource, instanceId: instanceId, handlers: handlers, missingHandler: missingHandler, logger: logger, handlerClient: rawHandlerClient, handlerResourceClients: rawHandlerResourceClients} = args, cascadeTelemetry = drainCascadeTelemetry(args.telemetry), {client: client, resourceClients: resourceClients} = taggedScope(args, REQUEST_TAG.drain), leaseMs = args.leaseMs ?? DEFAULT_EFFECT_LEASE_MS, clock = args.clock ?? wallClock, handlerClient = effectHandlerClient(rawHandlerClient), handlerResourceClients = effectHandlerResolver(rawHandlerResourceClients), routeGdr = buildClientForGdr({
+    const {tag: tag, workflowResource: workflowResource, instanceId: instanceId, handlers: handlers, missingHandler: missingHandler, logger: logger, handlerClient: rawHandlerClient, handlerResourceClients: rawHandlerResourceClients} = args, cascadeTelemetry = drainCascadeTelemetry(args.telemetry), {client: client, resourceClients: resourceClients} = taggedScope(args, REQUEST_TAG.drain), leaseMs = args.leaseMs ?? DEFAULT_EFFECT_LEASE_MS, clock = args.clock ?? wallClock, sleep = args.sleep ?? wallSleeper, handlerClient = effectHandlerClient(rawHandlerClient), handlerResourceClients = effectHandlerResolver(rawHandlerResourceClients), routeGdr = buildClientForGdr({
         client: handlerClient,
         workflowResource: workflowResource,
         resourceClients: handlerResourceClients
@@ -13660,6 +14048,7 @@ async function drainEffectsInternal(args) {
         log: log,
         leaseMs: leaseMs,
         clock: clock,
+        sleep: sleep,
         ...executionContext !== void 0 ? {
             executionContext: executionContext
         } : {},
@@ -13667,14 +14056,14 @@ async function drainEffectsInternal(args) {
         drainerActor: drainerActor,
         clientFor: clientFor,
         buckets: buckets,
-        skippedKeys: /* @__PURE__ */ new Set
+        handledKeys: /* @__PURE__ */ new Set
     };
     for (;await drainOneCandidate(pass); ) ;
     return buckets;
 }
 
 async function drainOneCandidate(pass) {
-    const {client: client, tag: tag, instanceId: instanceId, buckets: buckets, skippedKeys: skippedKeys} = pass, now = pass.clock(), before = await reload({
+    const {client: client, tag: tag, instanceId: instanceId, buckets: buckets, handledKeys: handledKeys} = pass, now = pass.clock(), before = await reload({
         client: client,
         instanceId: instanceId,
         tag: tag
@@ -13683,7 +14072,7 @@ async function drainOneCandidate(pass) {
     const candidate = findClaimableCandidate({
         instance: before,
         now: now,
-        skippedKeys: skippedKeys
+        handledKeys: handledKeys
     });
     if (candidate === void 0) return !1;
     const handler = pass.handlers[candidate.name];
@@ -13692,7 +14081,7 @@ async function drainOneCandidate(pass) {
         candidate: candidate,
         instanceId: instanceId,
         log: pass.log
-    }), buckets.skipped.push(candidate), skippedKeys.add(candidate._key), !0;
+    }), buckets.skipped.push(candidate), handledKeys.add(candidate._key), !0;
     const claimed = await claimPendingEffect({
         client: client,
         instance: before,
@@ -13705,11 +14094,15 @@ async function drainOneCandidate(pass) {
         } : {}
     });
     if (claimed === void 0) return !0;
-    const outcome = await dispatchAndReport({
+    const retry = effectRetryPolicy(parseDefinitionSnapshot(before), candidate.name), outcome = await dispatchAndReport({
         handler: handler,
         candidate: candidate,
         claimToken: claimed.claimToken,
+        ...retry !== void 0 ? {
+            retry: retry
+        } : {},
         leaseMs: pass.leaseMs,
+        sleep: pass.sleep,
         client: client,
         handlerClient: pass.handlerClient,
         tag: tag,
@@ -13727,50 +14120,80 @@ async function drainOneCandidate(pass) {
         telemetry: pass.telemetry,
         clock: pass.clock
     });
-    return buckets[outcome].push(candidate), !0;
+    return buckets[outcome].push(candidate), outcome === "lost" && handledKeys.add(candidate._key), 
+    !0;
 }
 
-function findClaimableCandidate({instance: instance, now: now, skippedKeys: skippedKeys}) {
-    return instance.pendingEffects.find(e => (e.claim === void 0 || isClaimExpired(e.claim, now)) && !skippedKeys.has(e._key));
+function findClaimableCandidate({instance: instance, now: now, handledKeys: handledKeys}) {
+    return instance.pendingEffects.find(e => (e.claim === void 0 || isClaimExpired(e.claim, now)) && !handledKeys.has(e._key));
 }
 
 async function dispatchAndReport(args) {
-    const {handler: handler, candidate: candidate, claimToken: claimToken, leaseMs: leaseMs, client: client, handlerClient: handlerClient, tag: tag, workflowResource: workflowResource, resourceClients: resourceClients, instanceId: instanceId, clientFor: clientFor, logger: logger, log: log, executionContext: executionContext, telemetry: telemetry, clock: clock} = args, commitQueue = createEffectCommitQueue({
-        effectKey: candidate._key,
-        claimToken: claimToken,
-        commit: async req => {
-            await workflow.commitEffectOps({
-                client: client,
-                tag: tag,
-                workflowResource: workflowResource,
-                ...resourceClients !== void 0 ? {
-                    resourceClients: resourceClients
-                } : {},
-                ...executionContext !== void 0 ? {
-                    executionContext: executionContext
-                } : {},
-                ...telemetry !== void 0 ? {
-                    telemetry: telemetry
-                } : {},
-                instanceId: instanceId,
-                effectKey: candidate._key,
-                claimToken: claimToken,
-                ops: req.ops,
-                idempotencyKey: req.idempotencyKey,
-                leaseMs: leaseMs,
-                clock: clock
-            });
-        }
-    }), {outputs: outputs, ops: ops, dispatchError: dispatchError} = await dispatchEffect({
+    const {handler: handler, candidate: candidate, claimToken: claimToken, retry: retry, leaseMs: leaseMs, sleep: sleep, client: client, handlerClient: handlerClient, tag: tag, workflowResource: workflowResource, resourceClients: resourceClients, instanceId: instanceId, clientFor: clientFor, logger: logger, log: log, executionContext: executionContext, telemetry: telemetry, clock: clock} = args, attemptOnce = attempt => dispatchEffect({
         handler: handler,
         candidate: candidate,
-        queue: commitQueue,
+        queue: createEffectCommitQueue({
+            effectKey: candidate._key,
+            claimToken: claimToken,
+            attempt: attempt,
+            commit: async req => {
+                await workflow.commitEffectOps({
+                    client: client,
+                    tag: tag,
+                    workflowResource: workflowResource,
+                    ...resourceClients !== void 0 ? {
+                        resourceClients: resourceClients
+                    } : {},
+                    ...executionContext !== void 0 ? {
+                        executionContext: executionContext
+                    } : {},
+                    ...telemetry !== void 0 ? {
+                        telemetry: telemetry
+                    } : {},
+                    instanceId: instanceId,
+                    effectKey: candidate._key,
+                    claimToken: claimToken,
+                    ops: req.ops,
+                    idempotencyKey: req.idempotencyKey,
+                    leaseMs: leaseMs,
+                    clock: clock
+                });
+            }
+        }),
         ctx: {
             client: handlerClient,
             clientFor: clientFor,
             instanceId: instanceId,
             logger: logger
         }
+    }), claimed = {
+        client: client,
+        tag: tag,
+        instanceId: instanceId,
+        effectKey: candidate._key,
+        claimToken: claimToken
+    }, run = await runRetryPolicy({
+        attemptOnce: attemptOnce,
+        ...retry !== void 0 ? {
+            retry: retry
+        } : {},
+        clock: clock,
+        sleep: sleep,
+        holdThrough: holdMs => renewClaimLease({
+            ...claimed,
+            holdMs: holdMs,
+            clock: clock
+        }),
+        stillHeld: () => claimStillHeld(claimed),
+        leaseMs: leaseMs
+    });
+    if (run.abandoned !== void 0) return log.warn(run.abandoned === "lease" ? `Effect "${candidate.name}" could not hold its claim between retry attempts — the run stopped with attempts left` : `Effect "${candidate.name}" was settled by another party during a retry backoff — the run stopped without dispatching again`, {
+        effectKey: candidate._key,
+        instanceId: instanceId
+    }), "lost";
+    const {outputs: outputs, ops: ops, dispatchError: dispatchError} = run.dispatch, detail = retry === void 0 ? void 0 : completionDetail({
+        run: run,
+        retry: retry
     });
     try {
         await reportEffectOutcome({
@@ -13791,6 +14214,9 @@ async function dispatchAndReport(args) {
             outputs: outputs,
             ops: ops,
             dispatchError: dispatchError,
+            ...detail !== void 0 ? {
+                detail: detail
+            } : {},
             clock: clock
         });
     } catch (error) {
@@ -13803,6 +14229,71 @@ async function dispatchAndReport(args) {
     return dispatchError === void 0 ? "drained" : "failed";
 }
 
+async function runRetryPolicy(args) {
+    const {attemptOnce: attemptOnce, retry: retry, clock: clock} = args, startedAt = Date.parse(clock()), elapsed = () => Date.parse(clock()) - startedAt;
+    let attempt = 1, dispatch = await attemptOnce(attempt);
+    for (;dispatch.dispatchError !== void 0 && retry !== void 0; ) {
+        const at = {
+            attempt: attempt,
+            elapsedMs: elapsed()
+        }, stop = await waitForNextAttempt({
+            retry: retry,
+            at: at,
+            elapsed: elapsed,
+            pace: args
+        });
+        if (stop !== void 0) return {
+            ...stop,
+            dispatch: dispatch,
+            at: at
+        };
+        attempt += 1, dispatch = await attemptOnce(attempt);
+    }
+    return {
+        dispatch: dispatch,
+        at: {
+            attempt: attempt,
+            elapsedMs: elapsed()
+        },
+        windowClosed: !1
+    };
+}
+
+async function waitForNextAttempt(args) {
+    const {retry: retry, at: at, elapsed: elapsed} = args, {clock: clock, sleep: sleep, holdThrough: holdThrough, stillHeld: stillHeld, leaseMs: leaseMs} = args.pace, delay = nextRetryDelayMs(retry, at);
+    if (delay === void 0) return {
+        windowClosed: at.attempt < retry.attempts
+    };
+    const heldUntil = await holdThrough(delay + leaseMs);
+    if (heldUntil === void 0 || hasPassed(heldUntil, addMs(clock(), delay))) return {
+        windowClosed: !1,
+        abandoned: "lease"
+    };
+    if (retryWindowClosed(retry, elapsed() + delay)) return {
+        windowClosed: !0
+    };
+    if (await sleep(delay), !await stillHeld()) return {
+        windowClosed: !1,
+        abandoned: "settled"
+    };
+    if (retryWindowClosed(retry, elapsed())) return {
+        windowClosed: !0
+    };
+}
+
+function completionDetail(args) {
+    const {run: run, retry: retry} = args, {dispatchError: dispatchError} = run.dispatch;
+    return dispatchError === void 0 ? retrySucceededDetail({
+        at: run.at,
+        attempts: retry.attempts
+    }) : retryFailedDetail({
+        at: run.at,
+        attempts: retry.attempts,
+        error: dispatchError,
+        windowClosed: run.windowClosed
+    });
+}
+
 async function reportEffectOutcome(args) {
     const {outputs: outputs, ops: ops, dispatchError: dispatchError, resourceClients: resourceClients, ...rest} = args;
     await workflow.completeEffect({
@@ -14093,6 +14584,9 @@ function createInstanceSession(args) {
             definition: definitionOf(),
             actor: actor,
             snapshot: snapshotFrom(held, normalizedSelf),
+            documentAvailability: documentAvailabilityReader({
+                clientForGdr: evalScope.clientForGdr
+            }),
             guards: guards,
             resourceGrants: resourceGrants,
             guardDereference: clientGuardDereference(evalScope.client),
@@ -14506,6 +15000,9 @@ function createEngine(args) {
                 telemetry: telemetry,
                 ...args.effects?.leaseMs !== void 0 ? {
                     leaseMs: args.effects.leaseMs
+                } : {},
+                ...args.sleep !== void 0 ? {
+                    sleep: args.sleep
                 } : {}
             }), drained = result.drained;
             return (drained.length > 0 || emptyDrainDue()) && telemetry.log(WorkflowEffectsDrained, {
@@ -14527,27 +15024,43 @@ function createEngine(args) {
 const CONSENT_TAG = "telemetry.consent", BATCH_TAG = "telemetry.batch";
 
 function createTelemetryIntake(args) {
-    const {client: client, projectId: projectId, denied: denied = !1} = args;
+    const {client: client, projectId: projectId, denied: denied = !1, context: context} = args;
     let cachedConsent;
     return {
         resolveConsent: async () => denied ? {
             status: "denied"
         } : (cachedConsent !== void 0 || (cachedConsent = await client.request({
-            uri: "/intake/telemetry-status",
+            url: "/intake/telemetry-status",
             tag: CONSENT_TAG
         })), cachedConsent),
         sendEvents: batch => client.request({
-            uri: "/intake/batch",
+            url: "/intake/batch",
             method: "POST",
             body: {
                 projectId: projectId,
-                batch: batch
+                batch: context === void 0 ? batch : batch.map(event => withContext(event, context))
             },
             tag: BATCH_TAG
         })
     };
 }
 
+function withContext(event, context) {
+    if (!invariants.isRecord(event)) return event;
+    const existing = invariants.isRecord(event.context) ? event.context : {};
+    return {
+        ...event,
+        context: {
+            ...existing,
+            ...context
+        }
+    };
+}
+
+function _resolveTelemetryEnvironment(nodeEnv, fallback) {
+    return nodeEnv === "production" ? "production" : nodeEnv === "development" || nodeEnv === "test" ? "development" : fallback;
+}
+
 function isTelemetryEnvDenied(env) {
     return isTrueish(env.CI) || isTrueish(env.DO_NOT_TRACK);
 }
@@ -14570,6 +15083,16 @@ function isTrueish(value) {
     return normalized !== "0" && normalized !== "false";
 }
 
+function summary(documents, deleted) {
+    if (documents.length === 0) return "";
+    const titles = [ ...new Set(documents.map(document => document.title ?? document.target.field)) ].map(title => `“${title}”`).join(", ");
+    return documents.length === 1 ? `A document selected for ${titles} ${deleted ? "has been deleted" : "can’t be read by this workflow"}` : `${documents.length} documents selected for ${titles} ${deleted ? "have been deleted" : "can’t be read by this workflow"}`;
+}
+
+function _missingDocumentsSummary(documents) {
+    return [ summary(documents.filter(document => document.availability === "deleted"), !0), summary(documents.filter(document => document.availability !== "deleted"), !1) ].filter(Boolean).join(". ");
+}
+
 function groupSitesOf(definition) {
     const sites = [], workflow2 = declarationIndex({
         groups: definition.groups,
@@ -15463,6 +15986,16 @@ exports.WorkflowStageTransitioned = WorkflowStageTransitioned;
 
 exports.WorkflowStateDivergedError = WorkflowStateDivergedError;
 
+exports._additionalMissingDocuments = _additionalMissingDocuments;
+
+exports._fieldTargetLabel = _fieldTargetLabel;
+
+exports._missingDocumentsSummary = _missingDocumentsSummary;
+
+exports._requestProjectMembers = _requestProjectMembers;
+
+exports._resolveTelemetryEnvironment = _resolveTelemetryEnvironment;
+
 exports.abortReason = abortReason;
 
 exports.acceptsDocumentType = acceptsDocumentType;
@@ -15575,6 +16108,8 @@ exports.documentStuckCause = documentStuckCause;
 
 exports.effectOutputsMap = effectOutputsMap;
 
+exports.effectSites = effectSites;
+
 exports.entryDocRefs = entryDocRefs;
 
 exports.evaluateFromSnapshot = evaluateFromSnapshot;