Policies: enforce on upload or export (#6614)

Follow-up to #6604 (merged). Builds the Security policy out so it actually enforces, driven from the editor. ## What it does - **Run on upload or export** — a single choice in the wizard: enforce when a file is uploaded, or just before it's exported. - **Output** — enforced result is a **new version** of the file (default) or a **new file**, with optional filename prefix/suffix/auto-number ("Output filename" subsection; auto-number only for new files). - **Export enforcement** — exporting an export-mode file runs the policy first and downloads the enforced result; never hard-blocks (on failure the original downloads). For new-version policies the in-editor file is versioned too. Covers every export path incl. multi-file ZIP. A toast (glowing in the policy's accent while it runs) reports progress and fades after ~10s. - **Affordances** — a freshly enforced file briefly glows its policy accent and carries a shield badge. - **Config tidy-up** — removed the unwired Security setting fields + the wizard's review step; "Upgrade to enterprise" on locked categories; category accent in the detail/wizard headers. ## Notes - Builds on the manual-only (client-driven) policy model from #6587 (`trigger: null`, metadata in `output.options`), adding the `runOn` field + export-time enforcement. - The page-editor merge-export (no single source file) enforces + downloads but doesn't version in place. ## Verification typecheck (core + proprietary), eslint, prettier; proprietary suite (105) green; flows checked in-app.
2026-07-16 03:20:46 +02:00 · 2026-06-11 18:12:01 +01:00
parent 5fa5e12c64
commit 9ee0bc4b32
31 changed files with 529 additions and 123 deletions
@@ -222,6 +222,34 @@
  margin: 0 0 var(--space-2);
 }

+/* Sub-section header inside a settings card (e.g. "Output filename"). The field
+   directly below it carries data-first so the borders don't double up. */
+.pol-subhead {
+  padding: 0.55rem 0.875rem 0.4rem;
+  font-size: 0.625rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--color-text-4);
+  background: var(--color-surface);
+  border-top: 1px solid var(--color-border);
+}
+
+/* Position dropdown + custom-text input sitting on one row under the
+   "Output filename" subhead — the dropdown sizes to content, text fills. */
+.pol-name-row {
+  display: flex;
+  gap: var(--space-2);
+  align-items: center;
+}
+.pol-name-row > :first-child {
+  flex: 0 0 auto;
+}
+.pol-name-row > :last-child {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
 /* ---- Fields (PolicyFieldRow) — row inset matches SUI ListRow ---- */
 .pol-field {
  padding: 0.7rem 0.875rem;
@@ -112,14 +112,14 @@ describe("Policies right-sidebar surface", () => {
    }
  });

-  it("shows Security as active and the unbuilt categories as Coming soon", () => {
+  it("shows Security as active and the unbuilt categories as upgrade-gated", () => {
    renderHost();
    expect(screen.getAllByText("Active").length).toBeGreaterThanOrEqual(1);
    // Ingestion, Compliance, Routing, Retention are locked for this release.
-    expect(screen.getAllByText("Coming soon")).toHaveLength(4);
+    expect(screen.getAllByText("Upgrade to enterprise")).toHaveLength(4);
  });

-  it("does not open a Coming soon policy when its row is clicked", () => {
+  it("does not open an upgrade-gated policy when its row is clicked", () => {
    renderHost();
    fireEvent.click(screen.getByText("Ingestion"));
    // The locked row isn't a button — we stay on the list, nothing opens.
@@ -151,7 +151,9 @@ export function PoliciesSection({
                    </IconBadge>
                    <span className="pol-row-label">{cat.label}</span>
                    <span className="pol-row-trail">
-                      <span className="pol-row-soon">Coming soon</span>
+                      <span className="pol-row-soon">
+                        Upgrade to enterprise
+                      </span>
                    </span>
                  </div>
                );
@@ -80,8 +80,7 @@ interface PolicySetupWizardProps {
 * The shared policy wizard, used for both setup and edit. Two steps: Workflow
 * (the tool pipeline, reusing the Watch Folders builder) → Settings (the policy
 * fields + output/retry config). The workflow builder is kept mounted across
- * steps so the final action can trigger its save. (A Sources step exists in
- * code, gated off by SOURCES_IN_FLOW, for when non-editor sources return.)
+ * steps so the final action can trigger its save.
 */
 export function PolicySetupWizard({
  category,
@@ -113,8 +112,8 @@ export function PolicySetupWizard({
  );
  const [scopeNarrow, setScopeNarrow] = useState(initial.scopeTypes.length > 0);
  const [scopeTypes, setScopeTypes] = useState<string[]>(initial.scopeTypes);
-  // Reviewer is no longer configured in the flow (there's no human-review step),
-  // but the field is kept in the saved policy, defaulted to the signed-in user.
+  // Reviewer isn't shown in the flow; the field is still saved on the policy,
+  // defaulted to the signed-in user.
  const reviewerEmail = initial.reviewerEmail || user?.email || "";
  // Output + retry settings — the real, working folder settings (the engine
  // applies them). Pre-filled from the backing folder in edit mode.
@@ -129,6 +128,10 @@ export function PolicySetupWizard({
  const [retryDelayMinutes, setRetryDelayMinutes] = useState(
    initialFolder?.retryDelayMinutes ?? 5,
  );
+  // The editor event this policy runs on: input on upload, or output on export.
+  const [runOn, setRunOn] = useState<"upload" | "export">(
+    initial.runOn ?? "upload",
+  );
  const workflowSave = useRef<(() => void) | null>(null);
  const [submitting, setSubmitting] = useState(false);
  const [saveError, setSaveError] = useState<string | null>(null);
@@ -197,6 +200,7 @@ export function PolicySetupWizard({
        scopeTypes: scopeNarrow ? scopeTypes : [],
        reviewerEmail,
        folder: {
+          runOn,
          outputMode,
          outputName: outputName.trim(),
          outputNamePosition,
@@ -229,6 +233,7 @@ export function PolicySetupWizard({
        scopeTypes: scopeNarrow ? scopeTypes : [],
        reviewerEmail,
        folder: {
+          runOn,
          outputMode,
          outputName: outputName.trim(),
          outputNamePosition,
@@ -329,35 +334,69 @@ export function PolicySetupWizard({
        {step === 2 && (
          <>
            <p className="pol-desc">{category.desc}</p>
-            <Card padding="none">
-              {config.fields.map((f, i) => (
-                <PolicyFieldRow
-                  key={f.key}
-                  field={f}
-                  value={fieldValues[f.key]}
-                  first={i === 0}
-                  onChange={(v) =>
-                    setFieldValues((prev) => ({ ...prev, [f.key]: v }))
-                  }
-                />
-              ))}
-            </Card>
+            {config.fields.length > 0 && (
+              <Card padding="none">
+                {config.fields.map((f, i) => (
+                  <PolicyFieldRow
+                    key={f.key}
+                    field={f}
+                    value={fieldValues[f.key]}
+                    first={i === 0}
+                    onChange={(v) =>
+                      setFieldValues((prev) => ({ ...prev, [f.key]: v }))
+                    }
+                  />
+                ))}
+              </Card>
+            )}

            {/* Real, working output + retry settings (applied by the engine). */}
            <p className="pol-section-label">Output &amp; retries</p>
            <Card padding="none">
+              {/* The editor event the policy runs on: input on upload, or
+                  output on export (enforced before the file is exported). */}
+              <div className="pol-subhead">Run on</div>
              <div className="pol-field" data-first>
                <SettingsRow
-                  label="Output"
+                  label="Run on"
+                  control={
+                    <Select
+                      inputSize="sm"
+                      value={runOn}
+                      onChange={(e) =>
+                        setRunOn(e.target.value as "upload" | "export")
+                      }
+                      aria-label="Run on"
+                      options={[
+                        { value: "upload", label: "Upload" },
+                        { value: "export", label: "Export" },
+                      ]}
+                    />
+                  }
+                />
+              </div>
+              <div className="pol-subhead">Output</div>
+              <div className="pol-field" data-first>
+                <SettingsRow
+                  label="Output as"
                  control={
                    <Select
                      inputSize="sm"
                      value={outputMode}
-                      onChange={(e) =>
-                        setOutputMode(
-                          e.target.value as "new_file" | "new_version",
-                        )
-                      }
+                      onChange={(e) => {
+                        const mode = e.target.value as
+                          | "new_file"
+                          | "new_version";
+                        setOutputMode(mode);
+                        // Auto-number only applies to new files; a new version
+                        // replaces the file in place, so fall back to suffix.
+                        if (
+                          mode === "new_version" &&
+                          outputNamePosition === "auto-number"
+                        ) {
+                          setOutputNamePosition("suffix");
+                        }
+                      }}
                      aria-label="Output mode"
                      options={[
                        { value: "new_file", label: "New file" },
@@ -367,41 +406,40 @@ export function PolicySetupWizard({
                  }
                />
              </div>
-              <div className="pol-field">
-                <SettingsRow
-                  label="Add to filename"
-                  control={
-                    <Select
-                      inputSize="sm"
-                      value={outputNamePosition}
-                      onChange={(e) =>
-                        setOutputNamePosition(
-                          e.target.value as "prefix" | "suffix" | "auto-number",
-                        )
-                      }
-                      aria-label="Add to filename"
-                      options={[
-                        { value: "prefix", label: "Prefix" },
-                        { value: "suffix", label: "Suffix" },
-                        { value: "auto-number", label: "Auto-number" },
-                      ]}
-                    />
-                  }
-                />
-              </div>
-              <div className="pol-field">
-                <SettingsRow
-                  label="Text to add"
-                  control={
+              {/* Output filename: position + custom text together as one row. */}
+              <div className="pol-subhead">Output filename</div>
+              <div className="pol-field" data-first>
+                <div className="pol-name-row">
+                  <Select
+                    inputSize="sm"
+                    value={outputNamePosition}
+                    onChange={(e) =>
+                      setOutputNamePosition(
+                        e.target.value as "prefix" | "suffix" | "auto-number",
+                      )
+                    }
+                    aria-label="Filename position"
+                    options={[
+                      { value: "prefix", label: "Prefix" },
+                      { value: "suffix", label: "Suffix" },
+                      // Auto-number only makes sense for separate new files.
+                      ...(outputMode === "new_file"
+                        ? [{ value: "auto-number", label: "Auto-number" }]
+                        : []),
+                    ]}
+                  />
+                  {/* Auto-number names the file itself, so there's no custom
+                      text to add — only show the input for prefix/suffix. */}
+                  {outputNamePosition !== "auto-number" && (
                    <Input
                      inputSize="sm"
                      value={outputName}
                      onChange={(e) => setOutputName(e.target.value)}
-                      placeholder="optional"
-                      aria-label="Text to add"
+                      placeholder="Text to add (optional)"
+                      aria-label="Filename text"
                    />
-                  }
-                />
+                  )}
+                </div>
              </div>
              <div className="pol-field">
                <SettingsRow
@@ -96,7 +96,6 @@ export function PolicyToolConfig({
            </div>
            {tool.enabled &&
              (tool.operation === "redact" ? (
-                // Redact config is reduced to just the PII type picker.
                <div className="pol-tool-body">
                  <PolicyRedactConfig
                    parameters={tool.parameters}
@@ -109,8 +108,8 @@ export function PolicyToolConfig({
                // are fixed in the policy preset), so no settings are shown.
                <></>
              ) : tool.operation === "watermark" ? (
-                // Watermark: full settings minus the "Flatten PDF pages to
-                // images" toggle (hidden), with flatten forced on.
+                // Watermark settings with flatten hidden + forced on (see
+                // PolicyWatermarkConfig).
                <div className="pol-tool-body">
                  <PolicyWatermarkConfig
                    parameters={tool.parameters}
@@ -73,14 +73,19 @@ export function usePolicyAutoRun(): void {
  useEffect(() => {
    if (!POLICIES_ENABLED) return;
    const active = Object.entries(policies).filter(
-      ([, s]) => s.configured && s.status === "active" && s.backendId,
+      ([, s]) =>
+        s.configured &&
+        s.status === "active" &&
+        s.backendId &&
+        // Only auto-run on upload when the policy is set to run on upload
+        // (export-triggered policies enforce at export time instead).
+        (s.runOn ?? "upload") === "upload",
    );
    for (const [categoryId, s] of active) {
      for (const stub of fileStubs) {
        const key = dispatchKey(categoryId, stub.id);
-        // Skip if already run (persisted) or a dispatch is mid-flight (this
-        // session) — runPolicyOnFile now waits for the file's bytes to commit,
-        // so the in-memory guard, not an eager mark, prevents double-firing.
+        // Skip if already run (persisted) or a dispatch is in flight — the
+        // in-memory guard prevents double-firing during the async wait.
        if (isDispatched(categoryId, stub.id) || dispatching.current.has(key)) {
          continue;
        }
@@ -5,7 +5,9 @@ describe("policy definitions integrity", () => {
  it("every category has a matching config entry", () => {
    for (const cat of POLICY_CATEGORIES) {
      expect(POLICY_CONFIG[cat.id], `config for ${cat.id}`).toBeDefined();
-      expect(POLICY_CONFIG[cat.id].fields.length).toBeGreaterThan(0);
+      // A category may have no policy-level setting fields (e.g. Security's were
+      // all unwired and removed); fields is required but can be empty.
+      expect(Array.isArray(POLICY_CONFIG[cat.id].fields)).toBe(true);
      expect(POLICY_CONFIG[cat.id].rules.length).toBeGreaterThan(0);
      // Every preset seeds a real, non-empty pipeline (the category→steps map).
      expect(
@@ -200,29 +200,9 @@ export const POLICY_CONFIG: Record<string, PolicyConfigDef> = {
      },
    ],
    scopeLabel: "All PDFs on this device",
-    // Policy-level controls only — detection/encryption/signing/watermark are
-    // per-tool and now live in the Workflow step.
-    fields: [
-      {
-        label: "User can override",
-        key: "userOverride",
-        type: "toggle",
-        value: true,
-      },
-      {
-        label: "Default access level",
-        key: "defaultAccess",
-        type: "select",
-        value: "Restricted",
-        options: ["Open", "Restricted", "Confidential", "Top Secret"],
-      },
-      {
-        label: "Block external sharing",
-        key: "blockExternal",
-        type: "toggle",
-        value: false,
-      },
-    ],
+    // No policy-level setting fields: tool config lives in the Workflow step;
+    // output naming + retries are set in the wizard.
+    fields: [],
  },
  compliance: {
    summary:
@@ -52,6 +52,7 @@ const wizardResult = {
  scopeTypes: [],
  reviewerEmail: "[email protected]",
  folder: {
+    runOn: "upload" as const,
    outputMode: "new_file" as const,
    outputName: "",
    outputNamePosition: "prefix" as const,
@@ -130,6 +130,7 @@ export function usePolicies() {
        reviewerEmail: result.reviewerEmail,
        outputMode: result.folder.outputMode,
        outputName: result.folder.outputName,
+        runOn: result.folder.runOn,
      });
    },
    [],
@@ -165,6 +166,7 @@ export function usePolicies() {
        reviewerEmail: result.reviewerEmail,
        outputMode: result.folder.outputMode,
        outputName: result.folder.outputName,
+        runOn: result.folder.runOn,
      });
    },
    [],
@@ -228,6 +230,7 @@ export function usePolicies() {
        reviewerEmail: result.reviewerEmail,
        outputMode: result.folder.outputMode,
        outputName: result.folder.outputName,
+        runOn: result.folder.runOn,
      });
    },
    [],
@@ -4,6 +4,11 @@ import { loadPolicyCatalog } from "@app/services/policyCatalog";
 import { ROW_ACCENT } from "@app/components/policies/policyStatus";
 import type { FileItemPolicyRef } from "@app/components/shared/FileSidebarFileItem";

+/** How long after a run a badge counts as "recent" (drives the one-off glow).
+ *  Covers the run + import delay; old/reloaded runs fall outside it, so the glow
+ *  fires only just after a policy is applied, not on every page reload. */
+const RECENT_MS = 60_000;
+
 /** Policy accent name (ROW_ACCENT) → the CSS colour var the badge uses. */
 const ACCENT_VAR: Record<string, string> = {
  blue: "var(--color-blue)",
@@ -26,10 +31,12 @@ export function usePolicyFileBadges(): Map<string, FileItemPolicyRef[]> {
    const labelById = new Map(
      loadPolicyCatalog().categories.map((c) => [c.id, c.label]),
    );
+    const now = Date.now();
    const byFile = new Map<string, FileItemPolicyRef[]>();
    for (const run of runs) {
      const name = labelById.get(run.categoryId);
      if (!name) continue;
+      const recent = now - run.startedAt < RECENT_MS;
      for (const fileId of run.outputFileIds ?? []) {
        const list = byFile.get(fileId) ?? [];
        if (!list.some((p) => p.id === run.categoryId)) {
@@ -37,6 +44,7 @@ export function usePolicyFileBadges(): Map<string, FileItemPolicyRef[]> {
            id: run.categoryId,
            name,
            accentColor: ACCENT_VAR[ROW_ACCENT[run.categoryId] ?? "blue"],
+            recent,
          });
          byFile.set(fileId, list);
        }
@@ -53,6 +53,7 @@ export function decodedToState(
    fieldValues: decoded.fieldValues,
    outputMode: decoded.folder.outputMode,
    outputName: decoded.folder.outputName,
+    runOn: decoded.folder.runOn,
    folderId: localFolderId,
    backendId: decoded.id,
    // Catalog-category policies are built-in defaults (not deletable).
@@ -0,0 +1,192 @@
+/**
+ * Export-time policy enforcement. A policy whose `runOn` is "export" runs its
+ * pipeline on a file just before it leaves the editor; the enforced result is
+ * what gets exported. Core export handlers reach this via the `@app/*` alias
+ * (the open-source build ships a no-op stub).
+ *
+ * Export is never hard-blocked: on failure the original file is exported and a
+ * warning toast is shown. For "new version" policies, the run is also recorded
+ * so the mounted import effect versions the in-editor file, not just the
+ * download. Only PDFs are enforced.
+ */
+
+import { loadPolicies } from "@app/services/policyStorage";
+import { loadPolicyCatalog } from "@app/services/policyCatalog";
+import {
+  runStoredPolicy,
+  getPolicyRun,
+  downloadPolicyOutput,
+} from "@app/services/policyApi";
+import { recordRunStart } from "@app/components/policies/policyRunStore";
+import { ROW_ACCENT } from "@app/components/policies/policyStatus";
+import { alert, updateToast, dismissToast } from "@app/components/toast";
+import { POLICIES_ENABLED } from "@app/constants/featureFlags";
+
+/** Poll cadence + cap for a single export run (≈2.5 min worst case). */
+const POLL_MS = 2000;
+const MAX_POLLS = 75;
+/** How long the result toast lingers before fading out. */
+const TOAST_LINGER_MS = 10_000;
+const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const isPdf = (f: File) =>
+  f.type === "application/pdf" || /\.pdf$/i.test(f.name);
+
+interface ExportPolicy {
+  categoryId: string;
+  backendId: string;
+  label: string;
+  outputMode: "new_file" | "new_version";
+  /** The policy's accent as a CSS colour, for the toast glow. */
+  accent: string;
+}
+
+interface PolicyRunResult {
+  file: File;
+  runId: string;
+  outputs: { fileId: string; fileName: string }[];
+}
+
+/** Configured, active policies set to enforce on export (read from the cache). */
+function activeExportPolicies(): ExportPolicy[] {
+  if (!POLICIES_ENABLED) return [];
+  const labels = new Map(
+    loadPolicyCatalog().categories.map((c) => [c.id, c.label]),
+  );
+  return Object.entries(loadPolicies())
+    .filter(
+      ([, s]) =>
+        s.configured &&
+        s.status === "active" &&
+        s.backendId &&
+        s.runOn === "export",
+    )
+    .map(([id, s]) => ({
+      categoryId: id,
+      backendId: s.backendId as string,
+      label: labels.get(id) ?? "Policy",
+      outputMode: s.outputMode === "new_file" ? "new_file" : "new_version",
+      accent: `var(--color-${ROW_ACCENT[id] ?? "blue"})`,
+    }));
+}
+
+/** Run one policy on a file and resolve the enforced bytes + run info (throws on
+ *  failure). */
+async function runToCompletion(
+  backendId: string,
+  file: File,
+): Promise<PolicyRunResult> {
+  const runId = await runStoredPolicy(backendId, [file]);
+  for (let i = 0; i < MAX_POLLS; i++) {
+    await delay(POLL_MS);
+    let view;
+    try {
+      view = await getPolicyRun(runId);
+    } catch {
+      continue; // transient — keep polling within the cap.
+    }
+    if (view.status === "COMPLETED") {
+      const out = view.outputs?.[0];
+      if (!out) throw new Error("policy produced no output");
+      const blob = await downloadPolicyOutput(out.fileId);
+      // Keep the export's filename; only the bytes are the enforced result.
+      const enforced = new File([blob], file.name, {
+        type: blob.type || file.type || "application/pdf",
+      });
+      return { file: enforced, runId, outputs: view.outputs ?? [] };
+    }
+    if (view.status === "FAILED" || view.status === "CANCELLED") {
+      throw new Error(view.error || `policy run ${view.status.toLowerCase()}`);
+    }
+  }
+  throw new Error("policy run timed out");
+}
+
+/**
+ * Enforce every active export-policy on each PDF just before export, returning
+ * the files in order (enforced, or the original on failure). `fileIds[i]` is the
+ * workspace id of `files[i]` when known — used to version the in-editor file for
+ * "new version" policies. Non-PDFs pass through untouched, and a single toast
+ * (glowing in the policy's accent while it runs) fades a few seconds after the
+ * result.
+ */
+export async function enforceExportPolicies(
+  files: File[],
+  fileIds?: (string | undefined)[],
+): Promise<File[]> {
+  const active = activeExportPolicies();
+  const targets = files.flatMap((f, i) => (isPdf(f) ? [i] : []));
+  if (!active.length || targets.length === 0) return files;
+
+  const names = active.map((p) => p.label).join(", ");
+  const toastId = alert({
+    alertType: "neutral",
+    title: `Applying ${names}`,
+    body: `Enforcing ${
+      targets.length === 1 ? "your file" : `${targets.length} files`
+    } before export…`,
+    isPersistentPopup: true,
+    expandable: false,
+    glowColor: active[0].accent,
+  });
+
+  const out = [...files];
+  let failures = 0;
+  for (const i of targets) {
+    const file = files[i];
+    const fileId = fileIds?.[i];
+    try {
+      let current = file;
+      // The last "new version" policy's output is what versions the editor file
+      // (recording every policy would double-consume the same input).
+      let versionRun: PolicyRunResult & { categoryId: string };
+      let hasVersionRun = false;
+      for (const policy of active) {
+        const result = await runToCompletion(policy.backendId, current);
+        current = result.file;
+        if (policy.outputMode === "new_version" && fileId) {
+          versionRun = { ...result, categoryId: policy.categoryId };
+          hasVersionRun = true;
+        }
+      }
+      out[i] = current;
+      if (hasVersionRun && fileId) {
+        recordRunStart({
+          runId: versionRun!.runId,
+          categoryId: versionRun!.categoryId,
+          fileId,
+          fileName: file.name,
+          fileSize: file.size,
+          status: "COMPLETED",
+          outputs: versionRun!.outputs,
+          error: null,
+          startedAt: Date.now(),
+        });
+      }
+    } catch {
+      failures += 1; // leave out[i] as the original — never hard-block.
+    }
+  }
+
+  updateToast(
+    toastId,
+    failures
+      ? {
+          alertType: "warning",
+          title: "Exported without full enforcement",
+          body: `${failures} of ${targets.length} file(s) couldn't be processed and were exported as-is.`,
+          isPersistentPopup: false,
+          glowColor: undefined,
+        }
+      : {
+          alertType: "success",
+          title: `${names} applied`,
+          body: "Enforced before export.",
+          isPersistentPopup: false,
+          glowColor: undefined,
+        },
+  );
+  // update() doesn't reschedule auto-dismiss, so fade the result out explicitly.
+  window.setTimeout(() => dismissToast(toastId), TOAST_LINGER_MS);
+  return out;
+}
@@ -116,6 +116,7 @@ const samplePolicy = {
  reviewerEmail: "[email protected]",
  fieldValues: { minConfidence: "80%" },
  folder: {
+    runOn: "export" as const,
    outputMode: "new_version" as const,
    outputName: "secured",
    outputNamePosition: "suffix" as const,
@@ -133,7 +134,7 @@ describe("buildBackendPolicy", () => {
    expect(policy.steps).toEqual([
      { operation: "/api/v1/misc/compress-pdf", parameters: {} },
    ]);
-    // Trigger is null (browser-driven); extras ride in output.options.
+    // Manual-only policy: no server-side trigger, extras ride in output.options.
    expect(policy.trigger).toBeNull();
    expect(policy.output.options.categoryId).toBe("security");
    expect(policy.output.options.reviewerEmail).toBe("[email protected]");
@@ -35,7 +35,7 @@ export interface BackendPipelineDefinition {
  output: BackendOutputSpec;
 }

-/** A policy's automatic trigger ("schedule" | "folder-watch"); null means manual (run on demand). */
+/** How a stored policy is triggered ("manual" | "folder" | "schedule" | "s3"). */
 export interface BackendTriggerConfig {
  type: string;
  options: Record<string, unknown>;
@@ -49,7 +49,8 @@ export interface BackendPolicy {
  owner: string;
  /** Gates automatic triggering; an explicit run ignores it. */
  enabled: boolean;
-  /** Null = manual; these policies are run from the browser on uploaded files. */
+  /** Null for a manual-only (client-driven) policy — the editor fires runs on
+   *  upload/export via /run, so there's no server-side trigger. */
  trigger: BackendTriggerConfig | null;
  steps: BackendPipelineStep[];
  output: BackendOutputSpec;
@@ -189,7 +190,7 @@ export interface PolicyToStore {
 /** The decoded policy read back from the backend. */
 export interface DecodedPolicy {
  id: string;
-  /** The catalog category this policy maps to (from output.options.categoryId). */
+  /** The catalog category this policy maps to (from trigger.options.categoryId). */
  categoryId: string;
  name: string;
  enabled: boolean;
@@ -203,6 +204,7 @@ export interface DecodedPolicy {
 }

 const DEFAULT_FOLDER: PolicyFolderSettings = {
+  runOn: "upload",
  outputMode: "new_version",
  outputName: "",
  outputNamePosition: "prefix",
@@ -211,11 +213,16 @@ const DEFAULT_FOLDER: PolicyFolderSettings = {
 };

 /**
- * Map a frontend policy to the backend {@link BackendPolicy} for persistence. Trigger is null:
- * these policies are run from the browser on uploaded files, not fired by a backend trigger. The
- * backend models only name/enabled/trigger/steps/output, so all policy-level extras (categoryId,
- * sources, scope, reviewer, fields, output/retry settings, and the full automation for a lossless
- * UI round-trip) ride in `output.options`; `steps` carries the endpoint-mapped pipeline.
+ * Map a frontend policy to the backend {@link BackendPolicy} for persistence.
+ * Policies are manual-only (client-driven): the editor fires runs on upload /
+ * before export via /run, so `trigger` is null (a server-side folder-watch or
+ * schedule trigger doesn't fit the in-editor model, and a null trigger skips
+ * trigger validation on the backend). The backend models only
+ * name/enabled/trigger/steps/output, so the policy-level extras (categoryId,
+ * sources, scope, reviewer, fields) and the output + retry settings all ride in
+ * `output.options`; the full frontend automation is stashed in
+ * `output.options.automation` for a lossless UI round-trip (while `steps`
+ * carries the endpoint-mapped pipeline the engine runs, pre-built by the caller).
 */
 export function buildBackendPolicy(input: PolicyToStore): BackendPolicy {
  return {
@@ -234,6 +241,8 @@ export function buildBackendPolicy(input: PolicyToStore): BackendPolicy {
        maxRetries: input.folder.maxRetries,
        retryDelayMinutes: input.folder.retryDelayMinutes,
        automation: input.automation,
+        runOn: input.folder.runOn,
+        // Policy-level metadata (no trigger bag to hold it any more).
        categoryId: input.categoryId,
        sources: input.sources,
        scopeTypes: input.scopeTypes,
@@ -247,27 +256,29 @@ export function buildBackendPolicy(input: PolicyToStore): BackendPolicy {
 /** Decode a stored backend policy back into the frontend settings. */
 export function fromBackendPolicy(policy: BackendPolicy): DecodedPolicy {
  const output = policy.output.options;
+  // Metadata lives in output.options; legacy records kept it in trigger.options,
+  // so merge both (output wins) to decode either shape.
+  const meta = { ...(policy.trigger?.options ?? {}), ...output };
  const str = (v: unknown, fallback = "") =>
    typeof v === "string" ? v : fallback;
  const num = (v: unknown, fallback: number) =>
    typeof v === "number" ? v : fallback;
  return {
    id: policy.id,
-    categoryId: str(output.categoryId),
+    categoryId: str(meta.categoryId),
    name: policy.name,
    enabled: policy.enabled,
    automation: (output.automation as AutomationConfig | undefined) ?? null,
-    sources: Array.isArray(output.sources) ? (output.sources as string[]) : [],
-    scopeTypes: Array.isArray(output.scopeTypes)
-      ? (output.scopeTypes as string[])
+    sources: Array.isArray(meta.sources) ? (meta.sources as string[]) : [],
+    scopeTypes: Array.isArray(meta.scopeTypes)
+      ? (meta.scopeTypes as string[])
      : [],
-    reviewerEmail: str(output.reviewerEmail),
+    reviewerEmail: str(meta.reviewerEmail),
    fieldValues:
-      (output.fieldValues as DecodedPolicy["fieldValues"] | undefined) ?? {},
+      (meta.fieldValues as DecodedPolicy["fieldValues"] | undefined) ?? {},
    folder: {
-      // Default to versioning unless the stored policy explicitly says new_file,
-      // so a missing/legacy output.mode follows the new-version default rather
-      // than silently flipping a reconciled policy to spawning separate files.
+      runOn: meta.runOn === "export" ? "export" : "upload",
+      // Legacy/missing output.mode defaults to new_version, not new_file.
      outputMode: output.mode === "new_file" ? "new_file" : "new_version",
      outputName: str(output.name),
      outputNamePosition:
@@ -26,6 +26,8 @@ function defaultState(): PolicyState {
    outputMode: "new_version",
    // No rename by default — the output keeps the input's filename.
    outputName: "",
+    // Enforce on upload by default; export enforcement is the alternative.
+    runOn: "upload",
    // Every catalog category is a shipped, built-in policy → default (not
    // deletable). User-created policies (later) will set this false.
    isDefault: true,
@@ -132,6 +132,8 @@ export interface PolicyState {
   *  input's filename; when set, it's applied as a prefix/suffix per the policy's
   *  name-position setting. */
  outputName?: string;
+  /** When the policy runs: on "upload" or before "export". Defaults to "upload". */
+  runOn?: "upload" | "export";
  /**
   * The backing folder-trigger record (a Watched Folders `WatchedFolder`) that
   * holds this policy's editable steps (its automation), output config and run
@@ -160,6 +162,8 @@ export type PoliciesByCategory = Record<string, PolicyState>;
 * backing folder (the real, working settings reused from the folder setup).
 */
 export interface PolicyFolderSettings {
+  /** The editor event the policy runs on: "upload" or "export". */
+  runOn: "upload" | "export";
  outputMode: "new_file" | "new_version";
  outputName: string;
  outputNamePosition: "prefix" | "suffix" | "auto-number";