qbit-document-generation/foundation/src/main/java/com/kingsrook/qbits/documentgeneration/DocumentDefinitionService.java

/*
 * QQQ - Low-code Application Framework for Engineers.
 * Copyright (C) 2021-2025.  Kingsrook, LLC
 * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
 * contact@kingsrook.com
 * https://github.com/Kingsrook/
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


package com.kingsrook.qbits.documentgeneration;

import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Objects;
import java.util.Set;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
import com.kingsrook.qqq.backend.core.actions.permissions.TablePermissionSubType;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QBadRequestException;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;

/*******************************************************************************
 ** User-defined document configuration. Saving drafts never changes publication;
 ** publication freezes source, dimensions, script identity and asset versions.
 *******************************************************************************/
public class DocumentDefinitionService
{
   private final DocumentGenerationQBitConfig config;

   /*******************************************************************************
    ** Unpublished user-authored sources and a versioned asset manifest.
    *******************************************************************************/
   public record Draft(String pdfSource, String zplSource, String scriptArtifact, List<Integer> assetIds, String outputBaseName, String outputNameContextKey)
   {
      /***************************************************************************
       ** Existing direct callers keep the historical output naming convention.
       ***************************************************************************/
      public Draft(String pdfSource, String zplSource, String scriptArtifact, List<Integer> assetIds)
      {
         this(pdfSource, zplSource, scriptArtifact, assetIds, null, null);
      }
   }

   /*******************************************************************************
    ** Source editor snapshot with an optimistic revision token, not a mutable row.
    *******************************************************************************/
   public record DraftView(Integer templateId, Integer stockId, String sourceTable, Draft draft, String fingerprint) {}

   /*******************************************************************************
    ** Inject the host's isolated validation provider.
    *******************************************************************************/
   public DocumentDefinitionService(DocumentGenerationQBitConfig config)
   {
      this.config = Objects.requireNonNull(config);
   }

   /***************************************************************************
    ** Current draft/active and unfinished-work context pins for cold maintenance.
    ** The owner enforces its explicit metadata authority, never caller row access.
    ***************************************************************************/
   public List<String> publishedContextReferences(Set<String> targetTables, int limit) throws QException
   {
      return (GenerationWarmInventory.read(config, targetTables, limit));
   }

   /*******************************************************************************
    ** Create a business document type without a code deployment.
    *******************************************************************************/
   public Integer createType(String name) throws QException
   {
      GenerationSecurity.require("configure");
      return (GenerationStore.insert(GenerationTables.TYPE, new QRecord().withValue("name", text(name, 200))).getValueInteger("id"));
   }

   /***************************************************************************
    ** Rename a definition without changing its identity, geometry or revisions.
    ** Native UpdateAction retains the host's ordinary field-change audit path.
    ***************************************************************************/
   public void rename(String table, Integer id, String name) throws QException
   {
      GenerationSecurity.require("configure");
      if(table == null || !List.of(GenerationTables.TYPE, GenerationTables.STOCK, GenerationTables.TEMPLATE).contains(table))
      {
         throw new QBadRequestException("Only document types, stock and templates can be renamed.");
      }
      String label = text(name, 200).strip();
      if(label.codePoints().anyMatch(Character::isISOControl))
      {
         throw new QBadRequestException("Document names cannot contain control characters.");
      }
      GenerationStore.atomic(List.of(table), () ->
      {
         GenerationStore.get(table, id);
         GenerationStore.update(table, new QRecord().withValue("id", id).withValue("name", label));
         return (null);
      });
   }

   /*******************************************************************************
    ** Stock geometry is immutable; changing a draft selects a new stock row.
    *******************************************************************************/
   public Integer createStock(String name, GenerationPorts.Stock stock) throws QException
   {
      GenerationSecurity.require("configure");
      validateStock(stock);
      QRecord row = stockRow(stock).withValue("name", text(name, 200));
      return (GenerationStore.insert(GenerationTables.STOCK, row).getValueInteger("id"));
   }

   /*******************************************************************************
    ** Bind a type to an actual host table with explicit permitted output formats.
    *******************************************************************************/
   public Integer bind(Integer typeId, String table, Boolean pdf, Boolean zpl) throws QException
   {
      GenerationSecurity.require("configure");
      GenerationStore.get(GenerationTables.TYPE, typeId);
      if(table == null || table.startsWith("document_generation_") || QContext.getQInstance().getTable(table) == null
         || !(Boolean.TRUE.equals(pdf) || Boolean.TRUE.equals(zpl)))
      {
         throw (new QBadRequestException("A source table and at least one format are required."));
      }
      return (GenerationStore.insert(GenerationTables.BINDING, new QRecord().withValue("typeId", typeId).withValue("tableName", table)
         .withValue("allowPdf", Boolean.TRUE.equals(pdf)).withValue("allowZpl", Boolean.TRUE.equals(zpl))).getValueInteger("id"));
   }

   /*******************************************************************************
    ** Stable template identities are permanently bound to their document type.
    *******************************************************************************/
   public Integer createTemplate(String name, Integer typeId, Integer stockId, String table) throws QException
   {
      GenerationSecurity.require("configure");
      binding(typeId, table);
      GenerationStore.get(GenerationTables.STOCK, stockId);
      return (GenerationStore.insert(GenerationTables.TEMPLATE, new QRecord().withValue("name", text(name, 200)).withValue("typeId", typeId)
         .withValue("stockId", stockId).withValue("tableName", table).withValue("outputBaseName", "document")).getValueInteger("id"));
   }

   /*******************************************************************************
    ** Create a usable PDF draft and its owned setup rows in one transaction. No
    ** worker runs and nothing is published. Existing templates remain unchanged.
    *******************************************************************************/
   public Integer createPackingSlip(String name, String table, GenerationPorts.Stock stock) throws QException
   {
      GenerationSecurity.require("configure");
      text(name, 200);
      validateStock(stock);
      if(!config.getSourceTables().contains(table))
      {
         throw new QBadRequestException("Choose a configured source table.");
      }
      GenerationSecurity.requireRead(table);
      PermissionsHelper.checkTablePermissionThrowing(new QueryInput(table), TablePermissionSubType.READ);
      return (GenerationStore.atomic(List.of(GenerationTables.TYPE, GenerationTables.STOCK, GenerationTables.BINDING, GenerationTables.TEMPLATE), () ->
      {
         Integer type = createType(name);
         Integer paper = createStock(name, stock);
         bind(type, table, true, false);
         Integer template = createTemplate(name, type, paper, table);
         GenerationStore.update(GenerationTables.TEMPLATE, new QRecord().withValue("id", template)
            .withValue("pdfSource", packingSlipStarter()));
         return (template);
      }));
   }

   /*******************************************************************************
    ** The editable starter for NEW packing slips: a reference, optional sender, ship-to,
    ** notes and a line table from the context. Existing templates are never rewritten.
    ** It names its few supported fields and never enumerates the source record.
    *******************************************************************************/
   static String packingSlipStarter() throws QException
   {
      try(var input = DocumentDefinitionService.class.getResourceAsStream("/documentgeneration/packing-slip-starter.html"))
      {
         if(input == null)
         {
            throw new IllegalStateException("Packing slip starter resource is absent.");
         }
         return (new String(input.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8));
      }
      catch(java.io.IOException | IllegalStateException failure)
      {
         throw new QException("Packing slip starter is unavailable.");
      }
   }

   /*******************************************************************************
    ** Asset content belongs to Record Files; this is an immutable named reference.
    ** The renderer adapter reauthorizes asset versions for validation and use.
    *******************************************************************************/
   public Integer addAsset(Integer templateId, GenerationPorts.Asset asset) throws QException
   {
      GenerationSecurity.require("configure");
      GenerationStore.get(GenerationTables.TEMPLATE, templateId);
      if(asset == null || asset.name() == null || !asset.name().matches("[A-Za-z0-9][A-Za-z0-9._-]{0,199}")
         || asset.sha256() == null || !asset.sha256().matches("[a-f0-9]{64}"))
      {
         throw (new QBadRequestException("Asset name and SHA-256 are invalid."));
      }
      asset.validateFont();
      return (GenerationStore.insert(GenerationTables.ASSET, new QRecord().withValue("templateId", templateId).withValue("name", asset.name())
         .withValue("fileVersionId", text(asset.fileVersionId(), 255)).withValue("sha256", asset.sha256())
         .withValue("mediaType", text(asset.mediaType(), 128)).withValue("fontFamily", asset.fontFamily())
         .withValue("fontWeight", asset.fontWeight()).withValue("fontStyle", asset.fontStyle())).getValueInteger("id"));
   }

   /***************************************************************************
    ** Resolve retained metadata with the current actor, then atomically register
    ** and include the named asset in the exact draft the author inspected.
    ***************************************************************************/
   public Integer addSelectedAsset(Integer templateId, String name, String versionId, String family, Integer weight, String style, String expectedFingerprint) throws QException
   {
      GenerationSecurity.require("configure");
      GenerationStore.get(GenerationTables.TEMPLATE, templateId);
      var choice = GenerationAssetChoices.resolve(config, versionId);
      var asset = new GenerationPorts.Asset(name, choice.versionId(), choice.sha256(), choice.mediaType(), blank(family) ? null : family, weight, blank(style) ? null : style);
      asset.validateFont();
      return (GenerationStore.atomic(List.of(GenerationTables.TEMPLATE, GenerationTables.ASSET), () ->
      {
         GenerationStore.lockTemplate(templateId);
         requireFingerprint(GenerationStore.get(GenerationTables.TEMPLATE, templateId), expectedFingerprint);
         DraftView current = loadDraft(templateId);
         List<Integer> ids = new java.util.ArrayList<>(current.draft().assetIds());
         if(ids.size() >= 100)
         {
            throw new QBadRequestException("The template already contains the maximum asset count.");
         }
         Integer id = addAsset(templateId, asset);
         ids.add(id);
         saveDraft(templateId, current.stockId(), new Draft(current.draft().pdfSource(), current.draft().zplSource(), current.draft().scriptArtifact(), ids, current.draft().outputBaseName(), current.draft().outputNameContextKey()));
         return (id);
      }));
   }

   /*******************************************************************************
    ** Save bounded draft sources without activating them on generation requests.
    *******************************************************************************/
   public void saveDraft(Integer templateId, Integer stockId, Draft draft) throws QException
   {
      GenerationSecurity.require("configure");
      GenerationStore.get(GenerationTables.TEMPLATE, templateId);
      GenerationStore.get(GenerationTables.STOCK, stockId);
      if(draft == null || (blank(draft.pdfSource()) && blank(draft.zplSource()))
         || length(draft.pdfSource()) > 262144 || length(draft.zplSource()) > 262144 || length(draft.scriptArtifact()) > 255
         || draft.assetIds() == null || draft.assetIds().size() > 100)
      {
         throw (new QBadRequestException("Draft sources or asset manifest exceed the supported bounds."));
      }
      GenerationFileNames.validatePolicy(draft.outputBaseName(), draft.outputNameContextKey(), draft.scriptArtifact());
      List<Integer> ids = List.copyOf(draft.assetIds());
      assets(templateId, ids);
      GenerationStore.update(GenerationTables.TEMPLATE, new QRecord().withValue("id", templateId).withValue("stockId", stockId)
         .withValue("pdfSource", draft.pdfSource()).withValue("zplSource", draft.zplSource())
         .withValue("outputBaseName", draft.outputBaseName()).withValue("outputNameContextKey", draft.outputNameContextKey())
         .withValue("scriptArtifact", blank(draft.scriptArtifact()) ? null : draft.scriptArtifact())
         .withValue("assetIds", String.join(",", ids.stream().map(Object::toString).toList())));
   }

   /***************************************************************************
    ** Native source editing cannot submit an internal context reference. Preserve
    ** the current pin under the same optimistic draft lock as the source update.
    ***************************************************************************/
   public void saveSources(Integer templateId, Integer stockId, String pdf, String zpl, String expectedFingerprint) throws QException
   {
      GenerationSecurity.require("configure");
      GenerationStore.atomic(List.of(GenerationTables.TEMPLATE), () ->
      {
         GenerationStore.lockTemplate(templateId);
         requireFingerprint(GenerationStore.get(GenerationTables.TEMPLATE, templateId), expectedFingerprint);
         Draft current = loadDraft(templateId).draft();
         saveDraft(templateId, stockId, new Draft(pdf, zpl, current.scriptArtifact(), current.assetIds(), current.outputBaseName(), current.outputNameContextKey()));
         return (null);
      });
   }

   /***************************************************************************
    ** Edit output naming independently, preserving sources/assets under the lock.
    ***************************************************************************/
   public void saveOutputNaming(Integer templateId, String baseName, String contextKey, String expectedFingerprint) throws QException
   {
      GenerationSecurity.require("configure");
      GenerationStore.atomic(List.of(GenerationTables.TEMPLATE), () ->
      {
         GenerationStore.lockTemplate(templateId);
         requireFingerprint(GenerationStore.get(GenerationTables.TEMPLATE, templateId), expectedFingerprint);
         var current = loadDraft(templateId);
         var draft = current.draft();
         saveDraft(templateId, current.stockId(), new Draft(draft.pdfSource(), draft.zplSource(), draft.scriptArtifact(), draft.assetIds(),
            blank(baseName) ? null : baseName, blank(contextKey) ? null : contextKey));
         return (null);
      });
   }

   /***************************************************************************
    ** Included immutable metadata for a bounded native selector, never file bytes.
    ***************************************************************************/
   public record DraftAsset(Integer id, GenerationPorts.Asset asset) {}

   /***************************************************************************
    ** Only this template's current included references enter the native form.
    ***************************************************************************/
   public List<DraftAsset> includedAssets(Integer templateId) throws QException
   {
      GenerationSecurity.require("configure");
      List<Integer> ids = loadDraft(templateId).draft().assetIds();
      if(ids.size() > 100)
      {
         throw new QBadRequestException("The included asset manifest exceeds its bounds.");
      }
      List<GenerationPorts.Asset> values = assets(templateId, ids);
      List<DraftAsset> result = new ArrayList<>();
      for(int index = 0; index < ids.size(); index++)
      {
         result.add(new DraftAsset(ids.get(index), values.get(index)));
      }
      return (List.copyOf(result));
   }

   /***************************************************************************
    ** Remove only draft membership. Old asset rows/originals/revisions are retained.
    ***************************************************************************/
   public void removeIncludedAsset(Integer templateId, Integer assetId, String expectedFingerprint) throws QException
   {
      GenerationSecurity.require("configure");
      GenerationStore.atomic(List.of(GenerationTables.TEMPLATE), () ->
      {
         GenerationStore.lockTemplate(templateId);
         requireFingerprint(GenerationStore.get(GenerationTables.TEMPLATE, templateId), expectedFingerprint);
         DraftView current = loadDraft(templateId);
         requireIncluded(current, assetId);
         List<Integer> ids = new ArrayList<>(current.draft().assetIds());
         ids.remove(assetId);
         saveDraft(templateId, current.stockId(), new Draft(current.draft().pdfSource(), current.draft().zplSource(), current.draft().scriptArtifact(), ids, current.draft().outputBaseName(), current.draft().outputNameContextKey()));
         return (null);
      });
   }

   /***************************************************************************
    ** Reauthorize replacement bytes before the transaction, then recheck membership
    ** and draft identity under lock. Preserve alias/font face and manifest position.
    ***************************************************************************/
   public Integer replaceIncludedAsset(Integer templateId, Integer assetId, String versionId, String expectedFingerprint) throws QException
   {
      GenerationSecurity.require("configure");
      requireIncluded(loadDraft(templateId), assetId);
      var choice = GenerationAssetChoices.resolve(config, versionId);
      return (GenerationStore.atomic(List.of(GenerationTables.TEMPLATE, GenerationTables.ASSET), () ->
      {
         GenerationStore.lockTemplate(templateId);
         requireFingerprint(GenerationStore.get(GenerationTables.TEMPLATE, templateId), expectedFingerprint);
         DraftView current = loadDraft(templateId);
         requireIncluded(current, assetId);
         GenerationPorts.Asset previous = assets(templateId, List.of(assetId)).getFirst();
         if("font/ttf".equals(previous.mediaType()) != "font/ttf".equals(choice.mediaType()))
         {
            throw new QBadRequestException("Replace an image with an image, or a TrueType font with a TrueType font.");
         }
         Integer replacement = addAsset(templateId, new GenerationPorts.Asset(previous.name(), choice.versionId(), choice.sha256(), choice.mediaType(),
            previous.fontFamily(), previous.fontWeight(), previous.fontStyle()));
         List<Integer> ids = new ArrayList<>(current.draft().assetIds());
         ids.set(ids.indexOf(assetId), replacement);
         saveDraft(templateId, current.stockId(), new Draft(current.draft().pdfSource(), current.draft().zplSource(), current.draft().scriptArtifact(), ids, current.draft().outputBaseName(), current.draft().outputNameContextKey()));
         return (replacement);
      }));
   }

   /***************************************************************************
    ** Old, removed and other-template references are not current draft authority.
    ***************************************************************************/
   private static void requireIncluded(DraftView draft, Integer assetId) throws QBadRequestException
   {
      if(assetId == null || !draft.draft().assetIds().contains(assetId))
      {
         throw new QBadRequestException("Select an asset currently included in this draft.");
      }
   }

   /***************************************************************************
    ** Resolve current source-owner authority before the owned draft transaction.
    ** Clear is explicit; never infer it from an omitted or failed selection.
    ***************************************************************************/
   public void selectContextScript(Integer templateId, String selectionId, boolean clear, String expectedFingerprint) throws QException
   {
      GenerationSecurity.require("configure");
      GenerationStore.get(GenerationTables.TEMPLATE, templateId);
      if(clear == !blank(selectionId))
      {
         throw new QBadRequestException("Select a published context script or explicitly clear it.");
      }
      String reference = clear ? null : GenerationContextChoices.resolve(config, selectionId).reference();
      GenerationStore.atomic(List.of(GenerationTables.TEMPLATE), () ->
      {
         GenerationSecurity.require("configure");
         GenerationStore.lockTemplate(templateId);
         requireFingerprint(GenerationStore.get(GenerationTables.TEMPLATE, templateId), expectedFingerprint);
         DraftView current = loadDraft(templateId);
         saveDraft(templateId, current.stockId(), new Draft(current.draft().pdfSource(), current.draft().zplSource(), reference, current.draft().assetIds(), current.draft().outputBaseName(), current.draft().outputNameContextKey()));
         return (null);
      });
   }

   /*******************************************************************************
    ** Load the current draft for the native source editor under configure authority.
    *******************************************************************************/
   public DraftView loadDraft(Integer templateId) throws QException
   {
      if(QContext.getQSession() != null && QContext.getQSession().hasPermission("document-generation.publish"))
      {
         GenerationSecurity.require("publish");
      }
      else
      {
         GenerationSecurity.require("configure");
      }
      QRecord row = GenerationStore.get(GenerationTables.TEMPLATE, templateId);
      String manifest = row.getValueString("assetIds");
      List<Integer> ids = blank(manifest) ? List.of() : java.util.Arrays.stream(manifest.split(",")).map(Integer::valueOf).toList();
      return (new DraftView(templateId, row.getValueInteger("stockId"), row.getValueString("tableName"),
         new Draft(row.getValueString("pdfSource"), row.getValueString("zplSource"), row.getValueString("scriptArtifact"), ids, row.getValueString("outputBaseName"), row.getValueString("outputNameContextKey")), fingerprint(row)));
   }

   /*******************************************************************************
    ** Native editors cannot silently overwrite a draft changed since it was opened.
    *******************************************************************************/
   public void saveDraft(Integer templateId, Integer stockId, Draft draft, String expectedFingerprint) throws QException
   {
      GenerationSecurity.require("configure");
      GenerationStore.atomic(List.of(GenerationTables.TEMPLATE), () ->
      {
         GenerationStore.lockTemplate(templateId);
         requireFingerprint(GenerationStore.get(GenerationTables.TEMPLATE, templateId), expectedFingerprint);
         saveDraft(templateId, stockId, draft);
         return (null);
      });
   }

   /*******************************************************************************
    ** Validate in an isolated provider, then insert an immutable revision and
    ** atomically switch the active reference after locking and comparing its draft;
    ** generation pins the selected id and is unaffected by later publication.
    *******************************************************************************/
   public Integer publish(Integer templateId) throws QException
   {
      return (freeze(templateId, null, true));
   }

   /*******************************************************************************
    ** Publish exactly the editor revision the user reviewed.
    *******************************************************************************/
   public Integer publish(Integer templateId, String expectedFingerprint) throws QException
   {
      text(expectedFingerprint, 64);
      return (freeze(templateId, expectedFingerprint, true));
   }

   /*******************************************************************************
    ** Preview uses an immutable revision and never changes active publication.
    *******************************************************************************/
   Integer previewRevision(Integer templateId, String expectedFingerprint) throws QException
   {
      text(expectedFingerprint, 64);
      return (freeze(templateId, expectedFingerprint, false));
   }

   /*******************************************************************************
    ** Validate outside the application JVM, then atomically bind the unchanged
    ** draft to its immutable source/stock/assets/build snapshot.
    *******************************************************************************/
   private Integer freeze(Integer templateId, String expectedFingerprint, boolean publish) throws QException
   {
      String actor = GenerationSecurity.require(publish ? "publish" : "configure");
      QRecord draft = GenerationStore.get(GenerationTables.TEMPLATE, templateId);
      String captured = fingerprint(draft);
      if(expectedFingerprint != null)
      {
         requireFingerprint(draft, expectedFingerprint);
      }
      QRecord stock = GenerationStore.get(GenerationTables.STOCK, draft.getValueInteger("stockId"));
      if(blank(draft.getValueString("pdfSource")) && blank(draft.getValueString("zplSource")))
      {
         throw (new QBadRequestException("Save a template source before publication."));
      }
      GenerationPorts.Revision candidate = snapshot(null, templateId, draft, stock);
      String assetManifest = draft.getValueString("assetIds");
      validateStock(candidate.stock());
      GenerationFileNames.validatePolicy(candidate.outputBaseName(), candidate.outputNameContextKey(), candidate.scriptArtifact());
      if(candidate.scriptArtifact() != null)
      {
         config.getContextExecution().validatePublished(actor, candidate.scriptArtifact());
      }
      config.getRenderer().validate(actor, candidate);
      QRecord row = stockRow(candidate.stock()).withValue("templateId", templateId).withValue("tableName", candidate.sourceTable())
         .withValue("pdfSource", candidate.pdfSource()).withValue("zplSource", candidate.zplSource()).withValue("scriptArtifact", candidate.scriptArtifact())
         .withValue("outputBaseName", candidate.outputBaseName()).withValue("outputNameContextKey", candidate.outputNameContextKey())
         .withValue("assetIds", assetManifest).withValue("publishedBy", actor).withValue("purpose", publish ? "PUBLISHED" : "PREVIEW").withValue("draftFingerprint", captured);
      return (GenerationStore.atomic(List.of(GenerationTables.TEMPLATE, GenerationTables.REVISION), () ->
      {
         GenerationStore.lockTemplate(templateId);
         if(!actor.equals(GenerationSecurity.require(publish ? "publish" : "configure")))
         {
            throw (new QException("Publishing actor changed during validation."));
         }
         requireFingerprint(GenerationStore.get(GenerationTables.TEMPLATE, templateId), captured);
         Integer id = GenerationStore.insert(GenerationTables.REVISION, row).getValueInteger("id");
         if(publish)
         {
            GenerationStore.update(GenerationTables.TEMPLATE, new QRecord().withValue("id", templateId).withValue("publishedRevisionId", id));
         }
         return (id);
      }));
   }

   /*******************************************************************************
    ** Length framing binds every editable source field without JSON ambiguity.
    *******************************************************************************/
   private static String fingerprint(QRecord row)
   {
      StringBuilder text = new StringBuilder();
      for(String field : List.of("id", "stockId", "tableName", "pdfSource", "zplSource", "scriptArtifact", "assetIds"))
      {
         String value = row.getValueString(field);
         text.append(value == null ? -1 : value.length()).append(':');
         if(value != null)
         {
            text.append(value);
         }
      }
      if(row.getValueString("outputBaseName") != null || row.getValueString("outputNameContextKey") != null)
      {
         for(String field : List.of("outputBaseName", "outputNameContextKey"))
         {
            String value = row.getValueString(field);
            text.append(value == null ? -1 : value.length()).append(':');
            if(value != null)
            {
               text.append(value);
            }
         }
      }
      try
      {
         return (java.util.HexFormat.of().formatHex(java.security.MessageDigest.getInstance("SHA-256").digest(text.toString().getBytes(java.nio.charset.StandardCharsets.UTF_8))));
      }
      catch(java.security.NoSuchAlgorithmException impossible)
      {
         throw new IllegalStateException(impossible);
      }
   }

   /*******************************************************************************
    ** Reject a missing token as well as stale values on editor-originated saves.
    *******************************************************************************/
   private static void requireFingerprint(QRecord row, String expected) throws QBadRequestException
   {
      if(expected == null || !Objects.equals(expected, fingerprint(row)))
      {
         throw new QBadRequestException("Template draft changed; reload before saving, previewing or publishing.");
      }
   }

   /*******************************************************************************
    ** Pin the published immutable identity exactly once for each batch.
    *******************************************************************************/
   GenerationPorts.Revision published(Integer templateId) throws QException
   {
      QRecord template = GenerationStore.get(GenerationTables.TEMPLATE, templateId);
      Integer id = template.getValueInteger("publishedRevisionId");
      if(id == null)
      {
         throw (new QBadRequestException("This template has no published revision."));
      }
      return (revision(id));
   }

   /*******************************************************************************
    ** Resume a batch from its originally captured published revision.
    *******************************************************************************/
   GenerationPorts.Revision revision(Integer id) throws QException
   {
      QRecord row = GenerationStore.get(GenerationTables.REVISION, id);
      return (snapshot(id, row.getValueInteger("templateId"), row, row));
   }

   /*******************************************************************************
    ** Current binding policy is checked independently from revision pinning.
    *******************************************************************************/
   static QRecord binding(Integer typeId, String table) throws QException
   {
      List<QRecord> rows = GenerationStore.query(GenerationTables.BINDING, new QQueryFilter().withCriteria("typeId", QCriteriaOperator.EQUALS, typeId)
         .withCriteria("tableName", QCriteriaOperator.EQUALS, table).withLimit(1));
      if(rows.isEmpty())
      {
         throw (new QBadRequestException("Document type is not bound to this source table."));
      }
      return (rows.getFirst());
   }

   /*******************************************************************************
    ** Published sources and stock are copied, never resolved through live drafts.
    *******************************************************************************/
   private GenerationPorts.Revision snapshot(Integer id, Integer templateId, QRecord row, QRecord stock) throws QException
   {
      String manifest = row.getValueString("assetIds");
      List<Integer> assetIds = blank(manifest) ? List.of() : java.util.Arrays.stream(manifest.split(",")).map(Integer::valueOf).toList();
      return (new GenerationPorts.Revision(id, templateId, row.getValueString("tableName"), readStock(stock), row.getValueString("pdfSource"),
         row.getValueString("zplSource"), row.getValueString("scriptArtifact"), assets(templateId, assetIds), row.getValueString("outputBaseName"), row.getValueString("outputNameContextKey")));
   }

   /*******************************************************************************
    ** Require ownership of each asset reference and unique names in the manifest.
    *******************************************************************************/
   private List<GenerationPorts.Asset> assets(Integer templateId, List<Integer> ids) throws QException
   {
      List<GenerationPorts.Asset> assets = new ArrayList<>();
      HashSet<String> names = new HashSet<>();
      for(Integer id : ids)
      {
         QRecord row = GenerationStore.get(GenerationTables.ASSET, id);
         if(!Objects.equals(templateId, row.getValueInteger("templateId")) || !names.add(row.getValueString("name")))
         {
            throw (new QBadRequestException("Asset manifest contains another template's asset or a duplicate name."));
         }
         assets.add(new GenerationPorts.Asset(row.getValueString("name"), row.getValueString("fileVersionId"), row.getValueString("sha256"), row.getValueString("mediaType"),
            row.getValueString("fontFamily"), row.getValueInteger("fontWeight"), row.getValueString("fontStyle")));
      }
      return (List.copyOf(assets));
   }

   /*******************************************************************************
    ** Physical limits are explicit; dimensions are integers to avoid NaN/rounding.
    *******************************************************************************/
   static void validateStock(GenerationPorts.Stock stock) throws QBadRequestException
   {
      if(stock == null || stock.widthMicrons() == null || stock.heightMicrons() == null || stock.topMicrons() == null
         || stock.rightMicrons() == null || stock.bottomMicrons() == null || stock.leftMicrons() == null || stock.dpi() == null
         || stock.widthMicrons() < 1000 || stock.widthMicrons() > 2000000 || stock.heightMicrons() < 1000 || stock.heightMicrons() > 2000000
         || stock.topMicrons() < 0 || stock.rightMicrons() < 0 || stock.bottomMicrons() < 0 || stock.leftMicrons() < 0
         || (long) stock.topMicrons() + stock.bottomMicrons() >= stock.heightMicrons()
         || (long) stock.leftMicrons() + stock.rightMicrons() >= stock.widthMicrons() || stock.dpi() < 72 || stock.dpi() > 1200)
      {
         throw (new QBadRequestException("Invalid stock dimensions, margins or DPI."));
      }
   }

   /*******************************************************************************
    ** Store exact micrometre dimensions on the immutable revision.
    *******************************************************************************/
   private QRecord stockRow(GenerationPorts.Stock stock)
   {
      return (new QRecord().withValue("widthMicrons", stock.widthMicrons()).withValue("heightMicrons", stock.heightMicrons())
         .withValue("topMicrons", stock.topMicrons()).withValue("rightMicrons", stock.rightMicrons()).withValue("bottomMicrons", stock.bottomMicrons())
         .withValue("leftMicrons", stock.leftMicrons()).withValue("dpi", stock.dpi()));
   }

   /*******************************************************************************
    ** Reconstruct a physical snapshot from native metadata fields.
    *******************************************************************************/
   private GenerationPorts.Stock readStock(QRecord row)
   {
      return (new GenerationPorts.Stock(row.getValueInteger("widthMicrons"), row.getValueInteger("heightMicrons"), row.getValueInteger("topMicrons"),
         row.getValueInteger("rightMicrons"), row.getValueInteger("bottomMicrons"), row.getValueInteger("leftMicrons"), row.getValueInteger("dpi")));
   }

   /*******************************************************************************
    ** Names and opaque references have a nonempty bounded representation.
    *******************************************************************************/
   static String text(String value, int maximum) throws QBadRequestException
   {
      if(blank(value) || value.length() > maximum)
      {
         throw (new QBadRequestException("A required document value is missing or too long."));
      }
      return (value);
   }


   /*******************************************************************************
    ** Treat absent or whitespace-only source as empty.
    *******************************************************************************/
   private static boolean blank(String value)
   {
      return (value == null || value.isBlank());
   }


   /*******************************************************************************
    ** Measure optional source without treating absence as an error.
    *******************************************************************************/
   private static int length(String value)
   {
      return (value == null ? 0 : value.length());
   }

}