@sanity/workflow-engine 0.5.0 → 0.6.0

package/dist/index.js

@@ -722,22 +722,6 @@ async function queryGuardsAcross(clients, query, params) {
 function dedupById(guards) {
   return [...new Map(guards.map((g) => [g._id, g])).values()].sort((a, b) => a._id.localeCompare(b._id));
 }
-const TAG_RE = /^[a-z0-9][a-z0-9-]*$/;
-function validateTags(tags) {
-  if (tags.length === 0)
-    throw new Error("tags: must be a non-empty array");
-  for (const tag of tags)
-    if (!TAG_RE.test(tag))
-      throw new Error(
-        `tags: invalid tag "${tag}" \u2014 must match ${TAG_RE.source} (ASCII lowercase + digits + dashes, no leading dash, no dots)`
-      );
-}
-function canonicalTag(tags) {
-  return tags[0];
-}
-function tagScopeFilter(param = "engineTags") {
-  return `count(tags[@ in $${param}]) > 0`;
-}
 const GUARD_OWNER = "robot:workflow-engine", GUARD_LIFTED_PREDICATE = "true";
 function resolveGuard(guard, instance, stageName, now) {
   const ctx = { instance, now }, targets = resolveIdRefTargets(guard.match.idRefs, ctx);
@@ -795,13 +779,13 @@ async function retractStageGuards(args) {
       await client.getDocument(doc._id) && await client.patch(doc._id).set({ predicate: GUARD_LIFTED_PREDICATE }).commit();
 }
 async function deleteOrphanedDefinitionGuards(args) {
-  const { client, clientForGdr, workflowResource, definition, definitions, tags } = args, perClient = await guardsForDefinitionByClient({
+  const { client, clientForGdr, workflowResource, definition, definitions, tag } = args, perClient = await guardsForDefinitionByClient({
     client,
     clientForGdr,
     workflowResource,
     definition,
     definitions
-  }), ownPartitionPrefix = `${canonicalTag(tags)}.`;
+  }), ownPartitionPrefix = `${tag}.`;
   let count = 0;
   for (const { client: resourceClient, guards } of perClient) {
     const own = guards.filter((guard) => guard.sourceInstanceId.startsWith(ownPartitionPrefix));
@@ -990,7 +974,7 @@ async function resolveQueryValue(entry, source, ctx, client, defaultValue) {
     stage: ctx.stageName ?? null,
     task: ctx.taskName ?? null,
     now: ctx.now,
-    engineTags: ctx.tags ?? []
+    tag: ctx.tag
   });
   try {
     const fetchOptions = ctx.perspective !== void 0 ? { perspective: ctx.perspective } : void 0, result = await client.fetch(source.query, params, fetchOptions);
@@ -1157,7 +1141,7 @@ async function resolveStageStateEntries(args) {
       client,
       now,
       selfId: instance._id,
-      tags: instance.tags ?? [],
+      tag: instance.tag,
       stageName: stage.name,
       workflowResource: instance.workflowResource,
       // Allow stage-scope entries' `source: { type: "stateRead", scope:
@@ -1177,7 +1161,7 @@ async function resolveTaskStateEntries(args) {
       client,
       now,
       selfId: instance._id,
-      tags: instance.tags ?? [],
+      tag: instance.tag,
       stageName: stage.name,
       workflowResource: instance.workflowResource,
       taskName: task.name,
@@ -1399,6 +1383,16 @@ function findCurrentStageEntry(instance) {
 function findCurrentTasks(instance) {
   return findCurrentStageEntry(instance)?.tasks ?? [];
 }
+const TAG_RE = /^[a-z0-9][a-z0-9-]*$/;
+function validateTag(tag) {
+  if (!TAG_RE.test(tag))
+    throw new Error(
+      `tag: invalid tag "${tag}" \u2014 must match ${TAG_RE.source} (ASCII lowercase + digits + dashes, no leading dash, no dots)`
+    );
+}
+function tagScopeFilter() {
+  return "tag == $tag";
+}
 function definitionLookupGroq(explicit) {
   const scoped = `_type == "${WORKFLOW_DEFINITION_TYPE}" && name == $definition && ${tagScopeFilter()}`;
   return explicit ? `*[${scoped} && version == $version][0]` : `*[${scoped}] | order(version desc)[0]`;
@@ -1415,6 +1409,14 @@ function clientForDiscovery(defaultClient, clientForGdr, subjectGdrUri) {
     return defaultClient;
   }
 }
+async function reload(client, instanceId, tag) {
+  const doc = await client.getDocument(instanceId);
+  if (!doc)
+    throw new Error(`Workflow instance ${instanceId} not found`);
+  if (doc.tag !== tag)
+    throw new Error(`Workflow instance ${instanceId} not visible to this engine (tag mismatch)`);
+  return doc;
+}
 function effectsContextEntry(name, value) {
   const _key = randomKey();
   return typeof value == "string" ? { _key, _type: "effectsContext.string", name, value } : typeof value == "number" ? { _key, _type: "effectsContext.number", name, value } : typeof value == "boolean" ? { _key, _type: "effectsContext.boolean", name, value } : { _key, _type: "effectsContext.ref", name, value };
@@ -1430,7 +1432,7 @@ function buildInstanceBase(args) {
     _rev: "",
     _createdAt: now,
     _updatedAt: now,
-    tags: args.tags,
+    tag: args.tag,
     workflowResource: args.workflowResource,
     definition: args.definitionName,
     pinnedVersion: args.pinnedVersion,
@@ -1481,7 +1483,7 @@ async function spawnSubworkflows(ctx, mutation, task, sub, actor) {
       `Subworkflow depth limit (${MAX_SPAWN_DEPTH}) exceeded on task "${task.name}" of ${ctx.instance._id}. Ancestor chain: ${chain}`
     );
   }
-  const now = ctx.now, definition = await resolveDefinitionRef(ctx.client, sub.definition, ctx.instance.tags ?? []);
+  const now = ctx.now, definition = await resolveDefinitionRef(ctx.client, sub.definition, ctx.instance.tag);
   if (definition === null) {
     const versionLabel = sub.definition.version === void 0 || sub.definition.version === "latest" ? "latest" : `v${sub.definition.version}`;
     throw new Error(
@@ -1571,15 +1573,15 @@ function coerceSpawnGdr(raw, workflowResource) {
   }
   return typeof raw == "string" && raw.length > 0 ? { id: toUri(raw), type: "document" } : null;
 }
-async function resolveDefinitionRef(client, ref, tags) {
-  const wantsExplicit = typeof ref.version == "number", params = { definition: ref.name, engineTags: tags };
+async function resolveDefinitionRef(client, ref, tag) {
+  const wantsExplicit = typeof ref.version == "number", params = { definition: ref.name, tag };
   return wantsExplicit && (params.version = ref.version), await client.fetch(
     definitionLookupGroq(wantsExplicit),
     params
   ) ?? null;
 }
 async function prepareChildInstance(args) {
-  const { client, parent, definition, initialState, effectsContext, actor, now } = args, childTags = parent.tags ?? [], childPrefix = childTags[0] ?? "wf", workflowResource = parent.workflowResource, childDocId = `${childPrefix}.wf-instance.${randomKey()}`, childRef = { id: gdrFromResource(workflowResource, childDocId), type: WORKFLOW_INSTANCE_TYPE }, ancestors = [
+  const { client, parent, definition, initialState, effectsContext, actor, now } = args, childTag = parent.tag, workflowResource = parent.workflowResource, childDocId = `${childTag}.wf-instance.${randomKey()}`, childRef = { id: gdrFromResource(workflowResource, childDocId), type: WORKFLOW_INSTANCE_TYPE }, ancestors = [
     ...parent.ancestors,
     {
       id: selfGdr(parent),
@@ -1592,7 +1594,7 @@ async function prepareChildInstance(args) {
       client,
       now,
       selfId: childDocId,
-      tags: childTags,
+      tag: childTag,
       workflowResource,
       ...inheritedPerspective !== void 0 ? { perspective: inheritedPerspective } : {}
     },
@@ -1611,7 +1613,7 @@ async function prepareChildInstance(args) {
   ), base = buildInstanceBase({
     id: childDocId,
     now,
-    tags: childTags,
+    tag: childTag,
     workflowResource,
     definitionName: definition.name,
     pinnedVersion: definition.version,
@@ -2477,17 +2479,12 @@ async function fetchGrantsCached(requestFn, resourcePath) {
   }
 }
 async function evaluateInstance(args) {
-  const { client, tags, instanceId, resourceClients } = args, now = (args.clock ?? wallClock)();
-  validateTags(tags);
+  const { client, tag, instanceId, resourceClients } = args, now = (args.clock ?? wallClock)();
+  validateTag(tag);
   const { actor, grants } = await resolveAccess(client, {
     ...args.access !== void 0 ? { override: args.access } : {},
     ...args.grantsFromPath !== void 0 ? { grantsFromPath: args.grantsFromPath } : {}
-  }), instance = await client.getDocument(instanceId);
-  if (!instance)
-    throw new Error(`Workflow instance "${instanceId}" not found`);
-  if (!tags.some((t) => instance.tags?.includes(t)))
-    throw new Error(`Workflow instance "${instanceId}" not visible to this engine (tag mismatch)`);
-  const definition = parseDefinitionSnapshot(instance), snapshot = await hydrateSnapshot({ client, clientForGdr: resourceClients !== void 0 ? (parsed) => resourceClients(parsed) ?? client : () => client, instance }), guards = await verdictGuardsForInstance(client, instance._id);
+  }), instance = await reload(client, instanceId, tag), definition = parseDefinitionSnapshot(instance), snapshot = await hydrateSnapshot({ client, clientForGdr: resourceClients !== void 0 ? (parsed) => resourceClients(parsed) ?? client : () => client, instance }), guards = await verdictGuardsForInstance(client, instance._id);
   return evaluateFromSnapshot({
     instance,
     definition,
@@ -2628,22 +2625,21 @@ function lifecycleReason(instance, status, stageHasExits) {
 function disabled(action, reason) {
   return { action, allowed: !1, disabledReason: reason };
 }
-function definitionDocId(_workflowResource, prefix, definition, version) {
-  return `${prefix}.${definition}.v${version}`;
+function definitionDocId(_workflowResource, tag, definition, version) {
+  return `${tag}.${definition}.v${version}`;
 }
-async function sortByDependencies(client, definitions, tags, workflowResource) {
-  const prefix = canonicalTag(tags), byName = /* @__PURE__ */ new Map();
+async function sortByDependencies(client, definitions, tag, workflowResource) {
+  const byName = /* @__PURE__ */ new Map();
   for (const def of definitions) {
     const list = byName.get(def.name) ?? [];
     list.push(def), byName.set(def.name, list);
   }
   const findInBatch = (ref) => findRefInBatch(byName, ref);
   return await assertCrossBatchRefsDeployed(client, definitions, {
-    tags,
+    tag,
     workflowResource,
-    prefix,
     findInBatch
-  }), topoSortDefinitions(definitions, { workflowResource, prefix, findInBatch });
+  }), topoSortDefinitions(definitions, { workflowResource, tag, findInBatch });
 }
 function findRefInBatch(byName, ref) {
   const candidates = byName.get(ref.name);
@@ -2656,10 +2652,10 @@ function findRefInBatch(byName, ref) {
 async function assertCrossBatchRefsDeployed(client, definitions, ctx) {
   const missing = [];
   for (const def of definitions) {
-    const fromId = definitionDocId(ctx.workflowResource, ctx.prefix, def.name, def.version);
+    const fromId = definitionDocId(ctx.workflowResource, ctx.tag, def.name, def.version);
     for (const ref of refsOf(def)) {
       if (ctx.findInBatch(ref) !== void 0) continue;
-      const label = await resolveDeployedRefLabel(client, ref, ctx.tags);
+      const label = await resolveDeployedRefLabel(client, ref, ctx.tag);
       label !== void 0 && missing.push({ from: fromId, ref: label });
     }
   }
@@ -2671,8 +2667,8 @@ async function assertCrossBatchRefsDeployed(client, definitions, ctx) {
 `)
   );
 }
-async function resolveDeployedRefLabel(client, ref, tags) {
-  const wantsExplicit = typeof ref.version == "number", params = { definition: ref.name, engineTags: tags };
+async function resolveDeployedRefLabel(client, ref, tag) {
+  const wantsExplicit = typeof ref.version == "number", params = { definition: ref.name, tag };
   if (wantsExplicit && (params.version = ref.version), !await client.fetch(
     definitionLookupGroq(wantsExplicit),
     params
@@ -2681,7 +2677,7 @@ async function resolveDeployedRefLabel(client, ref, tags) {
 }
 function topoSortDefinitions(definitions, ctx) {
   const visited = /* @__PURE__ */ new Set(), visiting = /* @__PURE__ */ new Set(), ordered = [], visit = (def) => {
-    const id = definitionDocId(ctx.workflowResource, ctx.prefix, def.name, def.version);
+    const id = definitionDocId(ctx.workflowResource, ctx.tag, def.name, def.version);
     if (!visited.has(id)) {
       if (visiting.has(id))
         throw new Error(`workflow.deployDefinitions: dependency cycle involving "${id}"`);
@@ -2722,11 +2718,11 @@ function stableStringify(value) {
     ([a], [b]) => a.localeCompare(b)
   ).map(([k, v2]) => `${JSON.stringify(k)}:${stableStringify(v2)}`).join(",")}}`;
 }
-async function loadDefinition(client, definition, version, tags) {
+async function loadDefinition(client, definition, version, tag) {
   if (version !== void 0) {
     const doc = await client.fetch(
       definitionLookupGroq(!0),
-      { definition, version, engineTags: tags }
+      { definition, version, tag }
     );
     if (!doc)
       throw new Error(`Workflow definition ${definition} v${version} not deployed`);
@@ -2734,16 +2730,16 @@ async function loadDefinition(client, definition, version, tags) {
   }
   const latest = await client.fetch(definitionLookupGroq(!1), {
     definition,
-    engineTags: tags
+    tag
   });
   if (!latest)
     throw new Error(`No deployed definition for workflow ${definition}`);
   return latest;
 }
-async function loadDefinitionVersions(client, definition, tags) {
+async function loadDefinitionVersions(client, definition, tag) {
   return client.fetch(
-    `*[_type == "${WORKFLOW_DEFINITION_TYPE}" && name == $definition && count(tags[@ in $engineTags]) > 0] | order(version desc)`,
-    { definition, engineTags: tags }
+    `*[_type == "${WORKFLOW_DEFINITION_TYPE}" && name == $definition && ${tagScopeFilter()}] | order(version desc)`,
+    { definition, tag }
   );
 }
 async function abortInstance(args) {
@@ -2894,7 +2890,7 @@ function bareIdFromSpawnRef(uri) {
   }
 }
 async function resolveOperationContext(args) {
-  validateTags(args.tags);
+  validateTag(args.tag);
   const access = await resolveAccess(args.client, {
     ...args.access !== void 0 ? { override: args.access } : {},
     ...args.grantsFromPath !== void 0 ? { grantsFromPath: args.grantsFromPath } : {}
@@ -2928,16 +2924,6 @@ async function abortAndPropagate(args) {
 function buildClientForGdr(defaultClient, resolver) {
   return resolver === void 0 ? () => defaultClient : (parsed) => resolver(parsed) ?? defaultClient;
 }
-async function reload(client, instanceId, tags) {
-  const doc = await client.getDocument(instanceId);
-  if (!doc) throw new Error(`Workflow instance ${instanceId} not found`);
-  if (!intersectsTags(doc.tags, tags))
-    throw new Error(`Workflow instance ${instanceId} not visible to this engine (tag mismatch)`);
-  return doc;
-}
-function intersectsTags(docTags, engineTags) {
-  return !docTags || docTags.length === 0 ? !1 : engineTags.some((t) => docTags.includes(t));
-}
 function toEffectsContextEntries(ctx) {
   return Object.entries(ctx).map(([id, value]) => effectsContextEntry(id, value));
 }
@@ -2963,15 +2949,15 @@ async function applyAction(args) {
   })).ranOps;
 }
 async function deleteDefinition(args) {
-  const { client, tags, definition, version, cascade: cascade2, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, versions = await loadDefinitionVersions(client, definition, tags);
+  const { client, tag, definition, version, cascade: cascade2, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, versions = await loadDefinitionVersions(client, definition, tag);
   if (versions.length === 0)
     throw new Error(`No deployed definition for workflow ${definition}`);
   const targets = version === void 0 ? versions : versions.filter((d) => d.version === version);
   if (targets.length === 0)
     throw new Error(`Workflow definition ${definition} v${version} not deployed`);
   const lastVersionGoes = targets.length === versions.length;
-  await assertNoSpawnReferrers(client, tags, definition, targets, lastVersionGoes);
-  const instanceIds = await nonTerminalInstanceIds(client, tags, definition, version);
+  await assertNoSpawnReferrers(client, tag, definition, targets, lastVersionGoes);
+  const instanceIds = await nonTerminalInstanceIds(client, tag, definition, version);
   if (instanceIds.length > 0 && cascade2 !== !0)
     throw new Error(
       `Cannot delete ${definition}: ${instanceIds.length} non-terminal instance(s) exist (${previewIds(instanceIds)}). Pass cascade to abort them first \u2014 instances are aborted in place, never deleted.`
@@ -2992,7 +2978,7 @@ async function deleteDefinition(args) {
     workflowResource: args.workflowResource,
     definition,
     definitions: versions,
-    tags
+    tag
   }) : 0;
   return {
     name: definition,
@@ -3001,10 +2987,10 @@ async function deleteDefinition(args) {
     deletedGuardCount
   };
 }
-async function assertNoSpawnReferrers(client, tags, definition, targets, lastVersionGoes) {
+async function assertNoSpawnReferrers(client, tag, definition, targets, lastVersionGoes) {
   const deployed = await client.fetch(
     `*[_type == "${WORKFLOW_DEFINITION_TYPE}" && ${tagScopeFilter()}]`,
-    { engineTags: tags }
+    { tag }
   ), targetIds = new Set(targets.map((d) => d._id)), targetVersions = new Set(targets.map((d) => d.version)), referrers = deployed.filter((d) => !targetIds.has(d._id)).filter(
     (d) => refsOf(d).some(
       (ref) => ref.name === definition && (typeof ref.version == "number" ? targetVersions.has(ref.version) : lastVersionGoes)
@@ -3017,11 +3003,11 @@ async function assertNoSpawnReferrers(client, tags, definition, targets, lastVer
     );
   }
 }
-async function nonTerminalInstanceIds(client, tags, definition, version) {
+async function nonTerminalInstanceIds(client, tag, definition, version) {
   const versionFilter = version === void 0 ? "" : " && pinnedVersion == $version";
   return (await client.fetch(
     `*[_type == "${WORKFLOW_INSTANCE_TYPE}" && definition == $definition && ${tagScopeFilter()} && !defined(completedAt)${versionFilter}] | order(_id asc){_id}`,
-    { definition, engineTags: tags, ...version !== void 0 ? { version } : {} }
+    { definition, tag, ...version !== void 0 ? { version } : {} }
   )).map((doc) => doc._id);
 }
 async function abortInstances(args) {
@@ -3052,20 +3038,20 @@ const workflow = {
    * Cycles in the dependency graph error before any write happens.
    */
   deployDefinitions: async (args) => {
-    const { client, tags, workflowResource, definitions } = args;
-    validateTags(tags);
+    const { client, tag, workflowResource, definitions } = args;
+    validateTag(tag);
     for (const def of definitions)
       validateDefinition(def);
-    const ordered = await sortByDependencies(client, definitions, tags, workflowResource), results = [], prefix = canonicalTag(tags), tx = client.transaction();
+    const ordered = await sortByDependencies(client, definitions, tag, workflowResource), results = [], tx = client.transaction();
     let hasWrites = !1;
     for (const def of ordered) {
-      const id = definitionDocId(workflowResource, prefix, def.name, def.version), expected = {
+      const id = definitionDocId(workflowResource, tag, def.name, def.version), expected = {
         ...def,
         _id: id,
         _type: WORKFLOW_DEFINITION_TYPE,
-        tags
+        tag
       }, existing = await client.getDocument(id);
-      if (existing && intersectsTags(existing.tags, tags) && isDefinitionUnchanged(existing, expected)) {
+      if (existing && existing.tag === tag && isDefinitionUnchanged(existing, expected)) {
         results.push({ definition: def.name, version: def.version, status: "unchanged" });
         continue;
       }
@@ -3103,7 +3089,7 @@ const workflow = {
   startInstance: async (args) => {
     const {
       client,
-      tags,
+      tag,
       workflowResource,
       definition: definitionName,
       version,
@@ -3112,7 +3098,7 @@ const workflow = {
       effectsContext,
       instanceId,
       perspective
-    } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, definition = await loadDefinition(client, definitionName, version, tags), id = instanceId ?? `${canonicalTag(tags)}.wf-instance.${randomKey()}`;
+    } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, definition = await loadDefinition(client, definitionName, version, tag), id = instanceId ?? `${tag}.wf-instance.${randomKey()}`;
     if (definition.stages.find((s) => s.name === definition.initialStage) === void 0)
       throw new Error(
         `Initial stage "${definition.initialStage}" missing in ${definitionName} v${definition.version}`
@@ -3124,7 +3110,7 @@ const workflow = {
         client,
         now,
         selfId: id,
-        tags,
+        tag,
         workflowResource,
         ...perspective !== void 0 ? { perspective } : {}
       },
@@ -3132,7 +3118,7 @@ const workflow = {
     }), effectivePerspective = perspective ?? derivePerspectiveFromState(resolvedState), base = buildInstanceBase({
       id,
       now,
-      tags,
+      tag,
       workflowResource,
       definitionName: definition.name,
       pinnedVersion: definition.version,
@@ -3144,7 +3130,7 @@ const workflow = {
       initialStage: definition.initialStage,
       actor
     });
-    return await client.create(base), await primeInitialStage(client, id, actor, clientForGdr, clock), await cascade(client, id, actor, clientForGdr, clock), reload(client, id, tags);
+    return await client.create(base), await primeInitialStage(client, id, actor, clientForGdr, clock), await cascade(client, id, actor, clientForGdr, clock), reload(client, id, tag);
   },
   /**
    * Fire an action against a task. If the task is pending, it is
@@ -3159,19 +3145,19 @@ const workflow = {
   fireAction: async (args) => {
     const {
       client,
-      tags,
+      tag,
       instanceId,
       task,
       action,
       params,
       idempotent,
       resourceClients
-    } = args, { access, actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, before = await reload(client, instanceId, tags);
+    } = args, { access, actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, before = await reload(client, instanceId, tag);
     if (findOpenStageEntry(before)?.tasks.find((t) => t.name === task) === void 0 && idempotent === !0)
       return { instance: before, cascaded: 0, fired: !1 };
     const evaluation = await evaluateInstance({
       client,
-      tags,
+      tag,
       instanceId,
       access,
       clock,
@@ -3190,7 +3176,7 @@ const workflow = {
       ...params !== void 0 ? { params } : {}
     }), cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
     return {
-      instance: await reload(client, instanceId, tags),
+      instance: await reload(client, instanceId, tag),
       cascaded,
       fired: !0,
       ...ranOps !== void 0 ? { ranOps } : {}
@@ -3204,7 +3190,7 @@ const workflow = {
    * reference them. Cascades after.
    */
   completeEffect: async (args) => {
-    const { client, tags, instanceId, effectKey, status, outputs, detail, error, durationMs } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
+    const { client, tag, instanceId, effectKey, status, outputs, detail, error, durationMs } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
     await completeEffect({
       client,
       instanceId,
@@ -3218,7 +3204,7 @@ const workflow = {
     });
     const cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
     return {
-      instance: await reload(client, instanceId, tags),
+      instance: await reload(client, instanceId, tag),
       cascaded,
       fired: !0
     };
@@ -3233,11 +3219,11 @@ const workflow = {
    * affected instances and the engine re-evaluates.
    */
   tick: async (args) => {
-    const { client, tags, instanceId } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, current = await reload(client, instanceId, tags), guards = await verdictGuardsForInstance(client, current._id);
+    const { client, tag, instanceId } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, current = await reload(client, instanceId, tag), guards = await verdictGuardsForInstance(client, current._id);
     await assertInstanceWriteAllowed({ instance: current, guards, identity: actor.id });
     const cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
     return {
-      instance: await reload(client, instanceId, tags),
+      instance: await reload(client, instanceId, tag),
       cascaded,
       fired: cascaded > 0
     };
@@ -3248,8 +3234,8 @@ const workflow = {
    * upstream; this verb performs the mechanical move.
    */
   setStage: async (args) => {
-    const { client, tags, instanceId, targetStage, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
-    await reload(client, instanceId, tags);
+    const { client, tag, instanceId, targetStage, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
+    await reload(client, instanceId, tag);
     const result = await setStage({
       client,
       instanceId,
@@ -3258,7 +3244,7 @@ const workflow = {
       options: { ...actor !== void 0 ? { actor } : {}, clock, clientForGdr }
     }), cascaded = result.fired ? await cascade(client, instanceId, actor, clientForGdr, clock) : 0;
     return {
-      instance: await reload(client, instanceId, tags),
+      instance: await reload(client, instanceId, tag),
       cascaded,
       fired: result.fired
     };
@@ -3270,28 +3256,28 @@ const workflow = {
    * contract (propagated, not cascaded — the instance is terminal).
    */
   abortInstance: async (args) => {
-    const { client, tags, instanceId, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
-    await reload(client, instanceId, tags);
+    const { client, tag, instanceId, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
+    await reload(client, instanceId, tag);
     const fired = await abortAndPropagate({ client, instanceId, reason, actor, clientForGdr, clock });
     return {
-      instance: await reload(client, instanceId, tags),
+      instance: await reload(client, instanceId, tag),
       cascaded: 0,
       fired
     };
   },
   /**
-   * Fetch a workflow instance by id, scoped to the engine's tags.
+   * Fetch a workflow instance by id, scoped to the engine's tag.
    * Throws when the instance doesn't exist or isn't visible to this
    * engine.
    */
   getInstance: async (args) => {
-    const { client, tags, instanceId } = args;
-    return validateTags(tags), reload(client, instanceId, tags);
+    const { client, tag, instanceId } = args;
+    return validateTag(tag), reload(client, instanceId, tag);
   },
   guardsForInstance: async (args) => {
-    const { client, tags, instanceId, resourceClients } = args;
-    validateTags(tags);
-    const instance = await reload(client, instanceId, tags);
+    const { client, tag, instanceId, resourceClients } = args;
+    validateTag(tag);
+    const instance = await reload(client, instanceId, tag);
     return guardsForInstance({
       client,
       clientForGdr: buildClientForGdr(client, resourceClients),
@@ -3299,9 +3285,9 @@ const workflow = {
     });
   },
   guardsForDefinition: async (args) => {
-    const { client, tags, workflowResource, definition, resourceClients } = args;
-    validateTags(tags);
-    const definitions = await loadDefinitionVersions(client, definition, tags);
+    const { client, tag, workflowResource, definition, resourceClients } = args;
+    validateTag(tag);
+    const definitions = await loadDefinitionVersions(client, definition, tag);
     if (definitions.length === 0)
       throw new Error(`No deployed definition for workflow ${definition}`);
     return guardsForDefinition({
@@ -3313,22 +3299,21 @@ const workflow = {
     });
   },
   /**
-   * Run a caller-supplied GROQ query with the engine's tags bound as
-   * `$engineTags`. This does NOT rewrite the query — arbitrary GROQ
+   * Run a caller-supplied GROQ query with the engine's tag bound as
+   * `$tag`. This does NOT rewrite the query — arbitrary GROQ
    * can't be safely tag-scoped after the fact — so the CALLER MUST
-   * filter on `$engineTags` (e.g.
-   * `count(tags[@ in $engineTags]) > 0`). To guard against accidental
-   * cross-tenant reads, a query that never references `$engineTags` is
+   * filter on `$tag` (e.g. `tag == $tag`). To guard against accidental
+   * cross-partition reads, a query that never references `$tag` is
    * rejected before it reaches the lake. Caller is responsible for type
    * narrowing the result.
    */
   query: async (args) => {
-    const { client, tags, groq, params } = args;
-    if (validateTags(tags), !groq.includes("$engineTags"))
+    const { client, tag, groq, params } = args;
+    if (validateTag(tag), !/\$tag\b/.test(groq))
       throw new Error(
-        `workflow.query: query must filter on $engineTags to stay tag-scoped (e.g. "count(tags[@ in $engineTags]) > 0"); got: ${groq}`
+        `workflow.query: query must filter on $tag to stay tag-scoped (e.g. "tag == $tag"); got: ${groq}`
       );
-    return client.fetch(groq, { ...params, engineTags: tags });
+    return client.fetch(groq, { ...params, tag });
   },
   /**
    * Snapshot-aware GROQ — runs against the same in-memory view that
@@ -3347,9 +3332,9 @@ const workflow = {
    * without re-implementing hydration. Pure read — never writes.
    */
   queryInScope: async (args) => {
-    const { client, tags, instanceId, groq, params, resourceClients } = args, clock = args.clock ?? wallClock;
-    validateTags(tags);
-    const instance = await reload(client, instanceId, tags), clientForGdr = buildClientForGdr(client, resourceClients), snapshot = await hydrateSnapshot({ client, clientForGdr, instance }), reserved = buildParams({ instance, now: clock(), snapshot }), tree = parse(groq, { params: { ...reserved, ...params } });
+    const { client, tag, instanceId, groq, params, resourceClients } = args, clock = args.clock ?? wallClock;
+    validateTag(tag);
+    const instance = await reload(client, instanceId, tag), clientForGdr = buildClientForGdr(client, resourceClients), snapshot = await hydrateSnapshot({ client, clientForGdr, instance }), reserved = buildParams({ instance, now: clock(), snapshot }), tree = parse(groq, { params: { ...reserved, ...params } });
     return await (await evaluate(tree, {
       dataset: snapshot.docs,
       params: { ...reserved, ...params }
@@ -3359,13 +3344,13 @@ const workflow = {
    * List every pending effect on the instance. Returns the same entries
    * the runtime would see — claimed and unclaimed alike.
    */
-  listPendingEffects: async (args) => (await reload(args.client, args.instanceId, args.tags)).pendingEffects,
+  listPendingEffects: async (args) => (await reload(args.client, args.instanceId, args.tag)).pendingEffects,
   /**
    * Filter pending effects on the instance by criteria. `claimed`
    * filters on claim presence; `names` restricts to specific effect
    * names. Both filters compose (AND).
    */
-  findPendingEffects: async (args) => (await reload(args.client, args.instanceId, args.tags)).pendingEffects.filter((e) => !(args.claimed === !0 && e.claim === void 0 || args.claimed === !1 && e.claim !== void 0 || args.names !== void 0 && !args.names.includes(e.name))),
+  findPendingEffects: async (args) => (await reload(args.client, args.instanceId, args.tag)).pendingEffects.filter((e) => !(args.claimed === !0 && e.claim === void 0 || args.claimed === !1 && e.claim !== void 0 || args.names !== void 0 && !args.names.includes(e.name))),
   /**
    * Project the instance from a given actor's perspective. Returns a
    * `WorkflowEvaluation` with per-action verdicts (`allowed` + a
@@ -3406,18 +3391,18 @@ const workflow = {
    * record. (The per-task `spawnedInstances` field on the active stage
    * only exists while that stage is current; history survives.) Strips
    * the GDR URI on each `instanceRef` to a bare `_id`, fetches the
-   * instances, drops any that aren't visible to this engine's tags, and
+   * instances, drops any that aren't visible to this engine's tag, and
    * returns them sorted by `startedAt` ascending.
    *
    * Pass `task` to restrict to a single spawning task on the parent.
    */
   children: async (args) => {
-    const { client, tags, instanceId, task } = args;
-    validateTags(tags);
-    const parent = await reload(client, instanceId, tags), isSpawned = (h) => h._type === "spawned", ids = parent.history.filter(isSpawned).filter((h) => task === void 0 || h.task === task).flatMap((h) => bareIdFromSpawnRef(h.instanceRef.id));
+    const { client, tag, instanceId, task } = args;
+    validateTag(tag);
+    const parent = await reload(client, instanceId, tag), isSpawned = (h) => h._type === "spawned", ids = parent.history.filter(isSpawned).filter((h) => task === void 0 || h.task === task).flatMap((h) => bareIdFromSpawnRef(h.instanceRef.id));
     return ids.length === 0 ? [] : client.fetch(
       `*[_id in $ids && ${tagScopeFilter()}] | order(startedAt asc)`,
-      { ids, engineTags: tags }
+      { ids, tag }
     );
   },
   /**
@@ -3432,11 +3417,11 @@ const workflow = {
   }
 };
 async function verifyDeployedDefinitionsInternal(args) {
-  const { client, tags, effectHandlers, missingHandler, logger } = args;
-  validateTags(tags);
+  const { client, tag, effectHandlers, missingHandler, logger } = args;
+  validateTag(tag);
   const log = logger("verifyDeployedDefinitions"), definitions = await client.fetch(
     `*[_type == "${WORKFLOW_DEFINITION_TYPE}" && ${tagScopeFilter()}] | order(name asc, version asc)`,
-    { engineTags: tags }
+    { tag }
   ), seen = [], missingByName = /* @__PURE__ */ new Map();
   for (const def of definitions)
     seen.push({ name: def.name, version: def.version, _id: def._id }), walkEffectNames(def, (name, location) => {
@@ -3485,7 +3470,7 @@ function walkEffectNames(def, visit) {
 async function drainEffectsInternal(args) {
   const {
     client,
-    tags,
+    tag,
     workflowResource,
     resourceClients,
     instanceId,
@@ -3496,10 +3481,10 @@ async function drainEffectsInternal(args) {
     actor: drainerActor,
     ...args.access?.grants !== void 0 ? { grants: args.access.grants } : {}
   };
-  validateTags(tags);
+  validateTag(tag);
   const log = logger("drainEffects"), drained = [], failed = [], skipped = [], skippedKeys = /* @__PURE__ */ new Set();
   for (; ; ) {
-    const before = await reload(client, instanceId, tags), candidate = before.pendingEffects.find(
+    const before = await reload(client, instanceId, tag), candidate = before.pendingEffects.find(
       (e) => e.claim === void 0 && !skippedKeys.has(e._key)
     );
     if (candidate === void 0) break;
@@ -3516,7 +3501,7 @@ async function drainEffectsInternal(args) {
     });
     await reportEffectOutcome({
       client,
-      tags,
+      tag,
       workflowResource,
       ...resourceClients !== void 0 ? { resourceClients } : {},
       instanceId,
@@ -3586,7 +3571,7 @@ async function applyMissingHandler(policy, info, log) {
   }
 }
 function createInstanceSession(args) {
-  const { client, tags, clock } = args, clientForGdr = buildClientForGdr(client, args.resourceClients);
+  const { client, tag, clock } = args, clientForGdr = buildClientForGdr(client, args.resourceClients);
   let instance = asHeldInstance(args.instance), overlay = /* @__PURE__ */ new Map(), heldGuards = [], committing = !1, buffered;
   const selfUri = () => gdrFromResource(instance.workflowResource, instance._id), applyUpdate = (docs) => {
     const next = /* @__PURE__ */ new Map();
@@ -3647,7 +3632,7 @@ function createInstanceSession(args) {
       return commit(async (actor, held) => {
         await assertInstanceWriteAllowed({ instance, guards: heldGuards, identity: actor.id });
         const cascaded = await cascade(client, instance._id, actor, clientForGdr, clock, held);
-        return instance = await reload(client, instance._id, tags), { instance, cascaded, fired: cascaded > 0 };
+        return instance = await reload(client, instance._id, tag), { instance, cascaded, fired: cascaded > 0 };
       });
     },
     fireAction({ task, action, params }) {
@@ -3664,7 +3649,7 @@ function createInstanceSession(args) {
           ...clock !== void 0 ? { clock } : {},
           ...params !== void 0 ? { params } : {}
         }), cascaded = await cascade(client, instance._id, actor, clientForGdr, clock, held);
-        return instance = await reload(client, instance._id, tags), { instance, cascaded, fired: !0, ...ranOps !== void 0 ? { ranOps } : {} };
+        return instance = await reload(client, instance._id, tag), { instance, cascaded, fired: !0, ...ranOps !== void 0 ? { ranOps } : {} };
       });
     }
   };
@@ -3692,11 +3677,11 @@ const defaultLoggerFactory = (name) => ({
   }
 };
 function createEngine(args) {
-  const { client, workflowResource, tags, resourceClients, clock } = args;
-  validateTags(tags);
+  const { client, workflowResource, resourceClients, clock, tag } = args;
+  validateTag(tag);
   const effectHandlers = args.effectHandlers ?? {}, missingHandler = args.missingHandler ?? "fail", logger = args.loggerFactory ?? defaultLoggerFactory, bind = (rest) => ({
     client,
-    tags,
+    tag,
     workflowResource,
     ...resourceClients !== void 0 ? { resourceClients } : {},
     ...clock !== void 0 ? { clock } : {},
@@ -3704,7 +3689,7 @@ function createEngine(args) {
   });
   return {
     client,
-    tags,
+    tag,
     workflowResource,
     effectHandlers,
     missingHandler,
@@ -3720,11 +3705,11 @@ function createEngine(args) {
     setStage: (rest) => workflow.setStage(bind(rest)),
     abortInstance: (rest) => workflow.abortInstance(bind(rest)),
     deleteDefinition: (rest) => workflow.deleteDefinition(bind(rest)),
-    getInstance: ({ instanceId }) => workflow.getInstance({ client, tags, workflowResource, instanceId }),
-    subscriptionDocumentsForInstance: ({ instanceId }) => workflow.getInstance({ client, tags, workflowResource, instanceId }).then(subscriptionDocumentsForInstance),
+    getInstance: ({ instanceId }) => workflow.getInstance({ client, tag, workflowResource, instanceId }),
+    subscriptionDocumentsForInstance: ({ instanceId }) => workflow.getInstance({ client, tag, workflowResource, instanceId }).then(subscriptionDocumentsForInstance),
     instance: (instanceDoc, opts) => createInstanceSession({
       client,
-      tags,
+      tag,
       instance: instanceDoc,
       ...resourceClients !== void 0 ? { resourceClients } : {},
       ...clock !== void 0 ? { clock } : {},
@@ -3733,45 +3718,45 @@ function createEngine(args) {
     }),
     guardsForInstance: ({ instanceId }) => workflow.guardsForInstance({
       client,
-      tags,
+      tag,
       workflowResource,
       instanceId,
       ...resourceClients !== void 0 ? { resourceClients } : {}
     }),
     guardsForDefinition: ({ definition }) => workflow.guardsForDefinition({
       client,
-      tags,
+      tag,
       workflowResource,
       definition,
       ...resourceClients !== void 0 ? { resourceClients } : {}
     }),
     children: ({ instanceId, task }) => workflow.children({
       client,
-      tags,
+      tag,
       workflowResource,
       instanceId,
       ...task !== void 0 ? { task } : {}
     }),
     query: ({ groq, params }) => workflow.query({
       client,
-      tags,
+      tag,
       workflowResource,
       groq,
       ...params !== void 0 ? { params } : {}
     }),
     queryInScope: ({ instanceId, groq, params }) => workflow.queryInScope({
       client,
-      tags,
+      tag,
       workflowResource,
       instanceId,
       groq,
       ...params !== void 0 ? { params } : {},
       ...clock !== void 0 ? { clock } : {}
     }),
-    listPendingEffects: ({ instanceId }) => workflow.listPendingEffects({ client, tags, workflowResource, instanceId }),
+    listPendingEffects: ({ instanceId }) => workflow.listPendingEffects({ client, tag, workflowResource, instanceId }),
     findPendingEffects: ({ instanceId, claimed, names }) => workflow.findPendingEffects({
       client,
-      tags,
+      tag,
       workflowResource,
       instanceId,
       ...claimed !== void 0 ? { claimed } : {},
@@ -3779,7 +3764,7 @@ function createEngine(args) {
     }),
     drainEffects: ({ instanceId, access }) => drainEffectsInternal({
       client,
-      tags,
+      tag,
       workflowResource,
       ...resourceClients !== void 0 ? { resourceClients } : {},
       instanceId,
@@ -3790,7 +3775,7 @@ function createEngine(args) {
     }),
     verifyDeployedDefinitions: () => verifyDeployedDefinitionsInternal({
       client,
-      tags,
+      tag,
       effectHandlers,
       missingHandler,
       logger
@@ -3798,7 +3783,7 @@ function createEngine(args) {
   };
 }
 function docIdFor(def, target) {
-  return definitionDocId(target.workflowResource, canonicalTag(target.tags), def.name, def.version);
+  return definitionDocId(target.workflowResource, target.tag, def.name, def.version);
 }
 function diffStatus(existing, expected) {
   return existing === void 0 ? "create" : isDefinitionUnchanged(existing, expected) ? "unchanged" : "update";
@@ -3808,7 +3793,7 @@ function diffEntry(def, existingRaw, target) {
     ...def,
     _id: docId,
     _type: WORKFLOW_DEFINITION_TYPE,
-    tags: target.tags
+    tag: target.tag
   }, status = diffStatus(existingRaw, expected), existing = existingRaw ? stripSystemFields(existingRaw) : void 0;
   return {
     name: def.name,
@@ -4025,7 +4010,6 @@ export {
   assigneesOf,
   availableActions,
   buildSnapshot,
-  canonicalTag,
   compileGuard,
   computeDiffEntries,
   contentReleaseName,
@@ -4071,7 +4055,7 @@ export {
   subscriptionDocumentsForInstance,
   tagScopeFilter,
   validateDefinition,
-  validateTags,
+  validateTag,
   verdictGuardsForInstance,
   wallClock,
   workflow