ngx-t-workflow-typings 3.0.1 → 3.2.0

package/dist/interfaces/Config/ElementEditorConfigSection.interface.d.ts

@@ -65,6 +65,18 @@ export interface ElementEditorInnerSectionStepElementInterface {
         label: string;
         value: string;
     }>;
+    /**
+     * Renders the chip list as a MULTI-select, so the bound value is a `string[]`
+     * rather than one value.
+     *
+     * Already honoured at runtime — `t-dynamic-data-edit.component.html:183` binds
+     * `[multiple]="!!vm.editorConfigValue?.multipleSelection"` for every chip
+     * editor, and the workflow-level config (`ElementEditorConfig`) has always
+     * declared it. It was simply missing from the STEP-level declaration, so a
+     * step element that needed a multi-select (the document/print field lists)
+     * could not say so without a cast.
+     */
+    multipleSelection?: boolean;
     computedErrors?: ValidationError[];
     min?: number;
     max?: number;

package/dist/interfaces/Document/WorkFlowDocument.interface.d.ts

@@ -22,6 +22,21 @@ export interface SimilarityResult {
     view: boolean;
     relation: 'ancestor' | 'descendant' | 'sibling' | 'similar';
 }
+/**
+ * Document-level lifecycle state, written by the check-in / check-out flow.
+ *
+ * Distinct from {@link DocumentWorkflowStep.status}, which is a per-step
+ * `WorkflowStepStatus` on `processTree[]`. This one describes the document itself.
+ *
+ * Members are additive only — never remove one, since existing documents carry the
+ * value and Mongoose validates the whole document on `.save()`.
+ */
+export declare enum WorkFlowDocumentStatus {
+    /** Live document. Set on the original when a checked-out copy is checked back in. */
+    Active = "active",
+    /** Superseded check-out copy, retained for history. Set together with `archive: true`. */
+    Archived = "archived"
+}
 /**
  * The STORED fields of a workflow document (the `FormVal` collection), excluding
  * everything Mongoose adds at runtime (`_id`, `createdAt`, `updatedAt`).
@@ -59,6 +74,12 @@ export interface leanWorkFlowDocumentInterface {
         date: Date;
     };
     checkedOutDocId?: string;
+    /**
+     * Document lifecycle state. Optional: only documents that have been through the
+     * check-in / check-out flow carry it, so every document written before that
+     * feature — and every ordinary transaction — has no `status` at all.
+     */
+    status?: WorkFlowDocumentStatus;
     latestVersion: number;
     versions: Array<{
         versionNumber: number;
@@ -69,6 +90,56 @@ export interface leanWorkFlowDocumentInterface {
     /** UI-only: in-flight indicator. */
     busy?: boolean;
     SYSTEM_TAGS: ITransactionTag[];
+    /**
+     * Present when the document is a FINAL RECORD — see {@link DocumentSeal}.
+     *
+     * This is THE seal indicator every consumer reads. It travels with the document
+     * through every existing endpoint (list, detail, reports), so no surface needs a
+     * separate "is it sealed" call: presence is the answer, and the fields inside it
+     * carry who, when, and until when it can still be reversed.
+     */
+    seal?: DocumentSeal;
+}
+/**
+ * The stamp that makes a workflow document a final record: no further editing,
+ * check-out, archiving, restoring or deletion.
+ *
+ * Lives on the document (not only in the sealing ledger) because that is what makes
+ * enforcement atomic — the check-out guard tests `seal: { $exists: false }` in the
+ * same `$match` it already runs — and what lets every read path report the state
+ * without a join.
+ */
+export interface DocumentSeal {
+    /** When the record was sealed. */
+    at: Date;
+    /**
+     * Who sealed it. Name and email are SNAPSHOT at seal time, never looked up later:
+     * a record has to stay readable after the person leaves or is renamed.
+     */
+    by: {
+        userId: string;
+        name?: string;
+        email?: string;
+    };
+    /** Why, when the sealer gave a reason. */
+    reason?: string;
+    /** Digest algorithm, recorded so a later change to it stays verifiable. */
+    algo: 'sha256';
+    /** Hex digest of the record's canonical content at the moment of sealing. */
+    hash: string;
+    /**
+     * Which canonical-payload recipe produced {@link hash}. Verification compares this
+     * BEFORE comparing hashes, so a seal written by an older recipe reports "cannot be
+     * checked" rather than falsely reporting the record as altered.
+     */
+    payloadVersion: number;
+    /**
+     * The instant the seal becomes permanent. Before it, the sealer or an administrator
+     * may reverse the seal; after it, no code path does. Stored as an absolute instant
+     * rather than derived from a configured window, so changing that policy cannot move
+     * the terms a record was sealed under.
+     */
+    hardenAt: Date;
 }
 /** A hydrated workflow document: the stored fields plus the ones Mongoose adds. */
 export interface WorkFlowDocumentInterface extends leanWorkFlowDocumentInterface {

package/dist/interfaces/Document/WorkFlowDocument.interface.js

@@ -4,3 +4,19 @@ export var RecentlyViewedStatus;
     RecentlyViewedStatus["Complete"] = "complete";
     RecentlyViewedStatus["Action"] = "action";
 })(RecentlyViewedStatus || (RecentlyViewedStatus = {}));
+/**
+ * Document-level lifecycle state, written by the check-in / check-out flow.
+ *
+ * Distinct from {@link DocumentWorkflowStep.status}, which is a per-step
+ * `WorkflowStepStatus` on `processTree[]`. This one describes the document itself.
+ *
+ * Members are additive only — never remove one, since existing documents carry the
+ * value and Mongoose validates the whole document on `.save()`.
+ */
+export var WorkFlowDocumentStatus;
+(function (WorkFlowDocumentStatus) {
+    /** Live document. Set on the original when a checked-out copy is checked back in. */
+    WorkFlowDocumentStatus["Active"] = "active";
+    /** Superseded check-out copy, retained for history. Set together with `archive: true`. */
+    WorkFlowDocumentStatus["Archived"] = "archived";
+})(WorkFlowDocumentStatus || (WorkFlowDocumentStatus = {}));

package/dist/interfaces/Document/index.d.ts

@@ -1,4 +1,4 @@
-export type { RecentlyViewedParams, SimilarityResult, leanWorkFlowDocumentInterface, WorkFlowDocumentInterface, IRecentlyViewed, IRecentlyViewedCookie, } from './WorkFlowDocument.interface.js';
-export { RecentlyViewedStatus } from './WorkFlowDocument.interface.js';
+export type { RecentlyViewedParams, SimilarityResult, leanWorkFlowDocumentInterface, WorkFlowDocumentInterface, IRecentlyViewed, IRecentlyViewedCookie, DocumentSeal, } from './WorkFlowDocument.interface.js';
+export { RecentlyViewedStatus, WorkFlowDocumentStatus } from './WorkFlowDocument.interface.js';
 /** @deprecated Use the {@link RecentlyViewedStatus} enum. */
 export type { RecentlyViewedStatusType } from './WorkFlowDocument.interface.js';

package/dist/interfaces/Document/index.js

@@ -1 +1 @@
-export { RecentlyViewedStatus } from './WorkFlowDocument.interface.js';
+export { RecentlyViewedStatus, WorkFlowDocumentStatus } from './WorkFlowDocument.interface.js';

package/dist/interfaces/ProcessStep/DocumentWorkflowStep.interface.d.ts

@@ -121,6 +121,32 @@ export interface DocumentWorkflowStep extends ProcessStep {
      * @see LegacyDocumentWorkflowStep if a consumer still needs the opaque shape.
      */
     validations: StepValidationOverride[];
+    /**
+     * Escalation records stamped onto the step when it is written.
+     *
+     * @deprecated **DUE REVIEW — pending removal.** The workflow builder's escalation
+     * setup has been decommissioned, so nothing configures escalations any more and
+     * every write is an empty array. It is declared only because writers still emit the
+     * key (`osproc-be/src/services/form.ts:671, 1033, 1407`; also on that service's own
+     * step interface, `src/interfaces/IFormVal.ts:6`) and a typed step schema would
+     * otherwise drop it silently.
+     *
+     * Remove this field — and the writes — once it is confirmed no stored document
+     * carries a non-empty `escalations` array. Deliberately `unknown[]`, NOT the
+     * definition-side escalation-level shape, which is already withdrawn (see
+     * `WorkflowSubSchemas.schema.ts`).
+     */
+    escalations?: unknown[];
+    /**
+     * The working copy a check-in came from, stamped on the `checkin` step record.
+     *
+     * Evidence: written at
+     * `cartalist-client-server/src/api/repositories/TransactionRepository.ts:518`. The
+     * matching `versions[].tempDocId` is already declared on the FormVal schema; this is
+     * the same link on the step record, which is what ties a filed version to the edit
+     * that produced it.
+     */
+    tempDocId?: string;
 }
 export interface DocumentActivityLog extends DocumentWorkflowStep {
     /**

package/dist/interfaces/ProcessStep/ProcessStep.interface.d.ts

@@ -200,6 +200,62 @@ export interface ProcessStep extends IProcessNodeBase {
     adjudicationMicroFlowStepWithAssignPoints?: string;
     microFlow: string;
     formId?: string;
+    /**
+     * Hides this step's section from the transaction's SYSTEM DOC — the assembled
+     * document a transaction's whole team can read.
+     *
+     * A workflow accumulates form values step by step and the System Doc renders
+     * one section per step that captured any, so an internal or procedural step
+     * (an inbox triage, a routing capture, a step whose fields only exist to drive
+     * a decision gate) publishes its fields to everyone with access to the
+     * document. This flag is the admin's opt-out for exactly those steps.
+     *
+     * PRESENTATION ONLY, and only on that one surface:
+     *
+     * - The step still RUNS. Its form is still filled in, its values still land in
+     *   `document.form`, and every downstream reader — decision gates, bulk mail,
+     *   scheduling, reports — still resolves them. This is not access control and
+     *   must not be used as such; a hidden step's values remain readable through
+     *   the document payload.
+     * - The ACTIVITY LOG is unaffected. That surface is the audit trail: it must
+     *   keep showing every visit, by whom and when, whatever the document chooses
+     *   to publish.
+     *
+     * Owned by the workflow DEFINITION, never by a document's step record — an
+     * admin toggling it must change what an already-filed document renders, so
+     * consumers read it off the definition rather than a runtime snapshot.
+     *
+     * Absent/`false` means visible, so every workflow authored before this field
+     * existed keeps rendering exactly as it did.
+     */
+    hideFromDocument?: boolean;
+    /**
+     * `formControlName`s of this step's own form that are suppressed EVERYWHERE the
+     * document is presented — details and print alike.
+     *
+     * Use for a field the step needs but the record should not carry: an internal
+     * note, a routing selector, a scratch value a decision gate reads. The value is
+     * still captured and still reaches `document.form`; it simply is not published.
+     *
+     * @see hideFromDocument, which is the same decision one level up. A hidden STEP
+     * publishes nothing at all, so these lists are moot on one — precedence is
+     * step-hidden > field-hidden > printable, and consumers apply it in that order.
+     */
+    hiddenFields?: string[];
+    /**
+     * `formControlName`s of this step's own form that are shown on screen but left
+     * OUT OF PRINT.
+     *
+     * The third state of the publishing rule, and the only one that distinguishes
+     * the two surfaces: a field the team should be able to read in the document
+     * without it landing in the printed/PDF copy — working notes, a long internal
+     * justification, an attachment thumbnail that prints as a wall of nothing.
+     *
+     * Ignored for a field already in {@link hiddenFields} (that field is gone from
+     * both surfaces) and for a step with {@link hideFromDocument}. Absent means
+     * printable, so every field authored before this existed still prints.
+     */
+    nonPrintableFields?: string[];
     members?: string[];
     followUpOperations: BackEndFollowUpOperationInterface[];
     active?: boolean;

package/dist/interfaces/ProcessStep/WorkflowStepType.interface.d.ts

@@ -10,9 +10,19 @@ export declare enum WorkflowStepTypeEnum {
     PublicPortal = "publicPortal",
     Archive = "archive",
     Checkout = "checkout",
-    Checkin = "checkin"
+    Checkin = "checkin",
+    /**
+     * Record sealing. Like `Checkout`/`Checkin` these are custody events rather than
+     * steps a document moves through — they carry no `stepId` and no definition in any
+     * workflow — but they ARE persisted into `processTree`, which is why they belong in
+     * this enum: `iserve-shared-types/schemas/Workflow/WorkflowProcessTree.schema.ts`
+     * derives that column's `enum` constraint from these values, so a step type absent
+     * here cannot legally be written.
+     */
+    Seal = "seal",
+    Unseal = "unseal"
 }
-export type WorkflowStepTypes = WorkflowStepTypeEnum.Initiate | WorkflowStepTypeEnum.Review | WorkflowStepTypeEnum.Append | WorkflowStepTypeEnum.Process | WorkflowStepTypeEnum.Decision | WorkflowStepTypeEnum.End | WorkflowStepTypeEnum.BulkMail | WorkflowStepTypeEnum.Adjudication | WorkflowStepTypeEnum.PublicPortal | WorkflowStepTypeEnum.Archive | WorkflowStepTypeEnum.Checkout | WorkflowStepTypeEnum.Checkin;
+export type WorkflowStepTypes = WorkflowStepTypeEnum.Initiate | WorkflowStepTypeEnum.Review | WorkflowStepTypeEnum.Append | WorkflowStepTypeEnum.Process | WorkflowStepTypeEnum.Decision | WorkflowStepTypeEnum.End | WorkflowStepTypeEnum.BulkMail | WorkflowStepTypeEnum.Adjudication | WorkflowStepTypeEnum.PublicPortal | WorkflowStepTypeEnum.Archive | WorkflowStepTypeEnum.Checkout | WorkflowStepTypeEnum.Checkin | WorkflowStepTypeEnum.Seal | WorkflowStepTypeEnum.Unseal;
 /**
  * Placeholder step kinds the CLIENT fabricates for display. These are NEVER
  * persisted and are deliberately kept OUT of {@link WorkflowStepTypeEnum}.

package/dist/interfaces/ProcessStep/WorkflowStepType.interface.js

@@ -12,6 +12,16 @@ export var WorkflowStepTypeEnum;
     WorkflowStepTypeEnum["Archive"] = "archive";
     WorkflowStepTypeEnum["Checkout"] = "checkout";
     WorkflowStepTypeEnum["Checkin"] = "checkin";
+    /**
+     * Record sealing. Like `Checkout`/`Checkin` these are custody events rather than
+     * steps a document moves through — they carry no `stepId` and no definition in any
+     * workflow — but they ARE persisted into `processTree`, which is why they belong in
+     * this enum: `iserve-shared-types/schemas/Workflow/WorkflowProcessTree.schema.ts`
+     * derives that column's `enum` constraint from these values, so a step type absent
+     * here cannot legally be written.
+     */
+    WorkflowStepTypeEnum["Seal"] = "seal";
+    WorkflowStepTypeEnum["Unseal"] = "unseal";
 })(WorkflowStepTypeEnum || (WorkflowStepTypeEnum = {}));
 /**
  * Placeholder step kinds the CLIENT fabricates for display. These are NEVER

package/dist/interfaces/Requirements/StepReferenceRules.constant.js

@@ -650,12 +650,13 @@ export const STEP_REFERENCE_RULES = {
             label: 'Post title field',
             targetKind: ReferenceTargetKind.FormControlInMicroFlowForm,
             severity: StepRequirementSeverity.Warning,
-            message: "Names a control that is not in the micro-flow's initiate form — the form this step actually renders. WARNING only: no read site exists in the audited repositories (the portal front end is outside them), and the editor offers the workflow-wide union rather than that form, so a mismatch may be intentional.",
+            message: "Names a control that is not in the micro-flow's initiate form — the form this step actually renders. WARNING only: no read site is known in any of the repositories searched, and the editor offers the workflow-wide union rather than that form, so a mismatch may be intentional.",
             evidence: [
                 'W/shared/functions/hydrateStep.ts:99-108 (a public-portal node\'s form IS the micro-flow initiate form; the step has no `formId` of its own)',
                 'W/component/workflow-diagram/WorkflowStepDefault.ts:102-114 (`formId` is in neither array for this type)',
                 'W/component/workflow-diagram/processStepEditorConfig.ts:278-285 (picker scope is the workflow-wide union — the divergence)',
-                'T/Workflow/WorkflowProcessTree.schema.ts:46 (persisted; no reader in the four audited repositories)',
+                'T/Workflow/WorkflowProcessTree.schema.ts:46 (persisted)',
+                "SEARCH NOW EXHAUSTIVE (2026-08), correcting the previous wording: the earlier grading said 'no read site in the AUDITED repositories' and named the public portal front end as the gap. That gap is closed — `iserve-portal`, `cartalist-portalApp` and the portal BACKEND (`S/services/portal/PortalService.ts`, `S/controllers/portal.ts`) contain zero reads of `publicPortalConfig`. RETAINED DELIBERATELY nonetheless, unlike the sibling `controlName` field which was retired in the same pass: the owner's call was to keep this one. The warning grading is therefore what it always was — a hint, never a block — and the 'may be intentional' clause still governs.",
             ],
             requires: [ReferenceCatalog.Workflows, ReferenceCatalog.Forms],
             requiresExternalCatalog: true,
@@ -698,22 +699,6 @@ export const STEP_REFERENCE_RULES = {
             requires: [ReferenceCatalog.WorkflowInputs],
             requiresExternalCatalog: true,
         },
-        {
-            id: 'publicPortal.controlName',
-            stepType: WorkflowStepTypeEnum.PublicPortal,
-            field: 'controlName',
-            label: 'Step control name',
-            targetKind: ReferenceTargetKind.FormControlInMicroFlowForm,
-            severity: StepRequirementSeverity.Warning,
-            message: "Names a control that is not in the micro-flow's initiate form. WARNING only: no public-portal code path in the audited repositories dereferences it.",
-            evidence: [
-                'W/component/workflow-diagram/WorkflowStepDefault.ts:103 (requiredProperties)',
-                'W/component/workflow-diagram/processStepEditorConfig.ts:35-42 (generic control-name Input — no picker, so no scope is enforced at authoring time)',
-                'W/shared/functions/hydrateStep.ts:99-108',
-            ],
-            requires: [ReferenceCatalog.Workflows, ReferenceCatalog.Forms],
-            requiresExternalCatalog: true,
-        },
         {
             id: 'publicPortal.publicPortalFunctionalScoreSheetStep',
             stepType: WorkflowStepTypeEnum.PublicPortal,
@@ -762,6 +747,8 @@ export const STEP_REFERENCE_RULES = {
     [WorkflowStepTypeEnum.Archive]: [],
     [WorkflowStepTypeEnum.Checkout]: [],
     [WorkflowStepTypeEnum.Checkin]: [],
+    [WorkflowStepTypeEnum.Seal]: [],
+    [WorkflowStepTypeEnum.Unseal]: [],
 };
 /* -------------------------------------------------------------------------- */
 /* Workflow-level rules                                                       */
@@ -806,6 +793,19 @@ export const EXCLUDED_STEP_REFERENCES = [
     // `publicPortalFunctionalScoreSheetStep` target TYPE (scoreCreation), the
     // review `controlName` toggle rule, and the `postExpiryDateControlName` date
     // rule. They are no longer exclusions; see STEP_REFERENCE_RULES.
+    {
+        field: 'controlName',
+        stepType: WorkflowStepTypeEnum.PublicPortal,
+        reason: "THE FIELD NO LONGER EXISTS ON THIS TYPE. Retired 2026-08 together with its requirement entry: `WorkflowStepDefault.ts` no longer lists `controlName` in the public-portal `requiredProperties` or `properties`, so the editor offers no control to author it. A rule that can only fire on a value nothing can set and nothing can read is pure noise — and this one fired often, because the retired control was a free-text Input (no picker, no scope) while the rule resolved against the micro-flow's INITIATE form, three hops out. THE SEARCH IS NOW EXHAUSTIVE: the previous grading said 'no read site in the AUDITED repositories' and named the public portal front end as the gap. Both portal applications (`iserve-portal`, `cartalist-portalApp`) and the portal backend (`S/services/portal/PortalService.ts`, `S/controllers/portal.ts`) have since been searched and contain zero reads; `cartalist-portalApp` carries only a type declaration on its local `ProcessStep`. Every remaining reader in the estate is `stepType`-scoped to review or adjudication.",
+        evidence: [
+            'E/services/workflow.ts:322-325 (the only routing dereference, guarded by `stepType === Review`)',
+            'S/executiveDashboard/drilldown/predicates.ts:90-92 (`if (s.stepType === WorkflowStepTypeEnum.Review)` before the read)',
+            'P/app-configs/ngx-t-forms-config.service.ts:561,580,598 (the adjudication reads)',
+            'S/executiveDashboard/drilldown/getTransactionDrilldown.ts:57-61 (step-type-agnostic, but only widens a Mongo projection — no behaviour depends on it)',
+            'W/component/workflow-diagram/WorkflowStepDefault.ts (public-portal `requiredProperties` / `properties` — `controlName` removed from both)',
+            "STEP_TYPE_REQUIREMENTS[publicPortal].integrityNotes (the matching removal note)",
+        ],
+    },
     {
         field: 'workflowFormForScoreSheet',
         stepType: WorkflowStepTypeEnum.Adjudication,

package/dist/interfaces/Requirements/StepTypeRequirements.constant.js

@@ -480,22 +480,6 @@ export const STEP_TYPE_REQUIREMENTS = {
                 ],
                 graphValidatorCode: 'DECISION_GATE_NO_OUTPUTS',
             },
-            {
-                field: 'controlName',
-                label: 'Step control name',
-                type: StepFieldValueType.String,
-                severity: StepRequirementSeverity.Error,
-                actionLabel: 'Step control name',
-                hint: 'Set it in the "Step control name" field for the decision gate.',
-                message: 'Give the decision gate a control name — it is required before the gate can be saved.',
-                evidence: [
-                    'PRODUCT OWNER POLICY (2026-07): the decision gate\'s step control name is required. This is a POLICY requirement, not an interpreter requirement — see the tension below.',
-                    'W/component/workflow-diagram/WorkflowStepDefault.ts:149 (requiredProperties DOES list controlName — the descriptor agrees it is required).',
-                    'TENSION — NO KNOWN READ SITE: a prior engine audit found the gate resolver dereferences `controlName` nowhere. `W/component/workflow-diagram/function/getNextWorkflowStepFromDecisionGate.ts:12-43` reads only systemStep, outputs, decisionsCondition and connections; `W/services/workflow/workflow.service.ts:70-71,137-139` delegates to that resolver with no `controlName` read. If requiring it ever produces authoring friction, that is because this is a POLICY requirement, not an interpreter one — no read site justifies it and the demotion evidence still stands.',
-                    'W/component/workflow-diagram/processStepEditorConfig.ts:35-42 (generic control-name Input — the control that satisfies it).',
-                ],
-                divergesFromDescriptor: 'RESTORED to required (Error) per product owner policy (2026-07). A previous revision DEMOTED it to optional/warning on the AUDIT (c) finding that the decision-gate code path dereferences `controlName` nowhere — that finding still stands (see the NO KNOWN READ SITE note in evidence). The product owner requires it regardless; this is a policy requirement, honoured here, not an interpreter one. It re-aligns with `WorkflowStepDefault.ts:149`, which lists it in requiredProperties.',
-            },
         ],
         conditional: [],
         optional: [],
@@ -513,7 +497,7 @@ export const STEP_TYPE_REQUIREMENTS = {
             graphValidatorCode: 'DECISION_GATE_NO_OUTPUTS',
         },
         integrityNotes: [
-            "AUDIT (c) + PRODUCT OWNER POLICY (2026-07): `controlName` is in `WorkflowStepDefault.ts:149` requiredProperties but read by nothing in the decision path — the gate resolver (`getNextWorkflowStepFromDecisionGate.ts:12-43`) and `workflow.service.ts:70-71,137-139` dereference it nowhere. A prior revision demoted it to optional/warning on that basis. The product owner now requires it, so it is a REQUIRED (Error) rule above. RECORD OF THE TENSION: this is a POLICY requirement, not an interpreter one. No read site is currently known; if requiring it ever produces authoring friction, the AUDIT (c) 'no reader' finding is the reason to revisit the policy, not the interpreter. The promotion rests solely on the owner's decision and its re-alignment with the descriptor.",
+            "REMOVED (2026-08), superseding the 2026-07 policy. `controlName` carries no rule here, and `WorkflowStepDefault.ts` no longer lists it in this type's `requiredProperties` or `properties`, so the editor does not offer it. HISTORY, because this field has been flipped twice: AUDIT (c) found no reader and demoted it; the product owner restored it as an explicit POLICY requirement in 2026-07, with the standing note that authoring friction would be the trigger to revisit. That friction arrived, and the owner's 2026-08 decision is to remove it rather than require a value nothing consumes. THE EVIDENCE IS NOW STRONGER THAN 'no reader found': the engine RETURNS EARLY for this step type — `E/services/workflow.ts:315-317` (`if (definitionOfLastStep?.stepType === 'decision') return { processStep: definitionOfLastStep }`) sits ABOVE the only `controlName` dereference in the routing path (`:322-325`, guarded by `stepType === Review` besides). So the field is not merely unread on this path, it is unreachable on it. The gate resolver (`getNextWorkflowStepFromDecisionGate.ts:12-43`) and `workflow.service.ts:70-71,137-139` confirm the client mirror. Every other reader in the estate is `stepType`-scoped to review or adjudication (`S/executiveDashboard/drilldown/predicates.ts:90-92`, `P/app-configs/ngx-t-forms-config.service.ts:561,580,598`). Persisted values are inert, not migrated.",
             "`members` is in `properties` (`WorkflowStepDefault.ts:151`) but the type is a system step, and `workflowDiagramActions.ts:216,289` force `members: []` on every save when `systemStep === true`. The entry is dead.",
             "Per-branch `decisionsCondition.expression` is NOT encoded as a field rule here: `getNextWorkflowStepFromDecisionGate.ts:25-27` skips an outlet without one, and the graph validator already reports it as `DECISION_GATE_MISSING_CONDITION` (`validateWorkflow.ts`, the per-output loop that pushes it when `!isNonEmptyString(expression)`). Owned by the graph validator, deliberately not duplicated. WORDING ALIGNMENT: that code emits 'has no condition set, so no document will ever be sent down it. Give it a condition or remove it.' — this type's `outputs` required-rule message and `sockets` message are worded to agree (every branch needs its own condition, or it never receives a document). The graph validator is upgrading `DECISION_GATE_MISSING_CONDITION` from warning to error; that severity change is owned there, not here.",
         ],
@@ -1059,19 +1043,6 @@ export const STEP_TYPE_REQUIREMENTS = {
                 ],
                 divergesFromDescriptor: 'PROMOTED to error (corrected). Previously `warning` because the only reader found took the key as a request parameter. `osproc-be` reads it directly off the step to schedule the post-expiry job, and its absence makes the portal step self-complete instantly. It agrees with `WorkflowStepDefault.ts:104` after all. NOTE the pool also changes: the engine resolves it against the MAIN document\'s form (`document.form`), not the micro-flow initiate form the node renders.',
             },
-            {
-                field: 'controlName',
-                label: 'Step control name',
-                type: StepFieldValueType.String,
-                severity: StepRequirementSeverity.Warning,
-                actionLabel: 'Step control name',
-                message: 'Optional for a public portal step — nothing in the systems checked here reads it, so you can leave it blank.',
-                evidence: [
-                    'W/component/workflow-diagram/WorkflowStepDefault.ts:103 (requiredProperties)',
-                    'W/component/workflow-diagram/processStepEditorConfig.ts:35-42 (generic control-name Input)',
-                ],
-                divergesFromDescriptor: 'DEMOTED to warning. AUDIT (c): required by the descriptor, dereferenced by nothing on the public-portal path.',
-            },
         ],
         conditional: [],
         optional: [
@@ -1109,7 +1080,8 @@ export const STEP_TYPE_REQUIREMENTS = {
         sockets: LINEAR_SOCKETS,
         integrityNotes: [
             "DESCRIPTOR/BADGE CONFLICT: `elementTemplate.systemStep` is `false` (`WorkflowStepDefault.ts:119`) while `members` and `formId` are in NEITHER `properties` nor `requiredProperties` (`:102-114`). `nodeValidator.ts:5-12` therefore permanently badges every public-portal node with 'Node is missing: user form, members' — two fields the type deliberately does not use. Either the template should be `systemStep: true` or `nodeValidator` should exempt this type; owned by the library, not fixed here. NOTE the engine DEPENDS on the empty `members`: `E/services/workflow.ts:812-813` reaches the post-expiry branch only because `members?.length > 0` is false. Making this type a system step would be safe, but giving a public-portal step members would silently disable its expiry scheduling.",
-            'CORRECTED: three of the five `requiredProperties` were previously demoted to warnings for want of a reader. `postExpiryDateControlName` is now back at `error` — `osproc-be` reads it to schedule the post-expiry job (`E/services/workflow.ts:813-840`). `publicPortalConfig` and `controlName` remain at `warning`: re-checked against `osproc-be`, both still have ZERO occurrences anywhere in that repository, so the demotion holds for them.',
+            'CORRECTED: three of the five `requiredProperties` were previously demoted to warnings for want of a reader. `postExpiryDateControlName` is now back at `error` — `osproc-be` reads it to schedule the post-expiry job (`E/services/workflow.ts:813-840`). `publicPortalConfig` remains at `warning`: re-checked against `osproc-be`, it still has ZERO occurrences anywhere in that repository, so the demotion holds for it.',
+            "REMOVED (2026-08): `controlName` no longer appears here at all, and `WorkflowStepDefault.ts` no longer lists it in this type's `requiredProperties` or `properties`, so the editor does not offer it. The earlier revisions could only DEMOTE it (required -> warning) because the search for a reader was bounded by four repositories and the public portal FRONT END was outside them — an unaudited consumer is a reason to keep a field, not to delete it. That gap is now closed: the two portal applications (`iserve-portal`, `cartalist-portalApp`) and the portal BACKEND (`S/services/portal/PortalService.ts`, `S/controllers/portal.ts`) were searched and contain ZERO reads of `step.controlName` — `cartalist-portalApp` carries only a type declaration on its local `ProcessStep` model. With every consumer accounted for, a field nothing reads is not a warning to be silenced, it is a field to be removed: it cannot be got wrong, so it cannot be flagged. Persisted values are left untouched by the schema (`controlName` is still a real field for `review` and `adjudication` steps) and are simply inert on this type. See also the matching `EXCLUDED_STEP_REFERENCES` entry, which retires the cross-reference rule for the same reason.",
         ],
     },
     /* ====================================================================== */
@@ -1202,6 +1174,38 @@ export const STEP_TYPE_REQUIREMENTS = {
             'Synthesised by the server on check-in (`S/repositories/TransactionRepository.ts:512-520`) and treated identically to `checkout` by the interpreter (`workflow.service.ts:57-63`) and the status resolver (`workflow-document-utils.ts:347-350`).',
         ],
     },
+    /* ====================================================================== */
+    /* SEAL / UNSEAL — record custody, never authored                         */
+    /* ====================================================================== */
+    [WorkflowStepTypeEnum.Seal]: {
+        stepType: WorkflowStepTypeEnum.Seal,
+        label: 'Record Sealed',
+        origin: StepTypeOrigin.Runtime,
+        systemStep: null,
+        required: [],
+        conditional: [],
+        optional: [],
+        sockets: NO_SOCKET_EXPECTATION,
+        integrityNotes: [
+            'Not authorable: no palette entry, no step editor. A workflow can never contain a seal step — it is a custody event the server records when a completed document is made a final record.',
+            'Carries no `stepId`, so every "where is this document" reading must look past it; see `documentLifecycle.LIFECYCLE_EVENT_STEP_TYPES` (server) and `shared/utils/workflow-lifecycle.ts` (client).',
+            'Declared here because `processTree.stepType` derives its database `enum` constraint from this enum — a persisted step type absent from it cannot legally be written.',
+        ],
+    },
+    [WorkflowStepTypeEnum.Unseal]: {
+        stepType: WorkflowStepTypeEnum.Unseal,
+        label: 'Seal Reversed',
+        origin: StepTypeOrigin.Runtime,
+        systemStep: null,
+        required: [],
+        conditional: [],
+        optional: [],
+        sockets: NO_SOCKET_EXPECTATION,
+        integrityNotes: [
+            'Recorded only when a seal is reversed inside its grace window; past that window no code path produces this event.',
+            'Same custody-event rules as `seal` — never authored, no `stepId`, skipped by every step resolver.',
+        ],
+    },
 };
 /**
  * The 12 `WorkflowStepTypeEnum` members in a stable order, derived from the map

package/dist/interfaces/Workflow/WorkflowModel.interface.d.ts

@@ -1,5 +1,152 @@
 import type { DocumentSectionConfigurationsInterface } from '../DocumentSection/DocumentSectionConfigurations.interface.js';
 import type { ProcessStep } from '../ProcessStep/ProcessStep.interface.js';
+/**
+ * WHEN a transaction of a workflow may be archived, expressed as a window over
+ * the transaction's position in its own process tree.
+ *
+ * - `inflight-abandon` — anywhere EXCEPT a completed end step. Archiving is an
+ *   abandon: a request that should not proceed is taken off the active list
+ *   while it is still running. This is the behaviour every workflow had before
+ *   the policy existed, and remains the default.
+ * - `on-completion` — ONLY at a completed end step. The inverse reading:
+ *   archiving is records disposal, so finished work can be filed away and
+ *   nothing half-done can disappear.
+ * - `at-step` — only while the transaction sits on one of the `stepId`s listed
+ *   in {@link ArchivePolicy.steps}. Archiving becomes a particular step's own
+ *   affordance ("the people on Verification can bin it there, nobody else").
+ * - `always` — any position.
+ * - `never` — archiving is not offered at all. For registers that must retain
+ *   every transaction, this is the workflow-wide equivalent of what sealing does
+ *   to a single record.
+ *
+ * The `auto-*` presets sketched during design (auto-archive on completion, after
+ * a retention window, or on stale in-flight transactions) are deliberately NOT
+ * here: they need a scheduled runner and a system actor for the `processTree`
+ * marker. Adding them later only widens this union, so it is a non-breaking
+ * change for stored configs.
+ */
+export type ArchivePolicyPreset = 'inflight-abandon' | 'on-completion' | 'at-step' | 'always' | 'never';
+/**
+ * WHO may archive, once {@link ArchivePolicyPreset} says the transaction is in
+ * an archivable position.
+ *
+ * - `initiator` — a member of the workflow's initiate step. The only rule that
+ *   existed before this field, and the default.
+ * - `stepMembers` — the members of the step the transaction currently sits on.
+ *   The natural pairing with the `at-step` preset; also the answer to the
+ *   standing complaint that a step member who spots a bad transaction has to go
+ *   find its initiator to have it removed.
+ * - `admin` — department or organisation administrators (inclusive upwards),
+ *   the same right that already governs sealing.
+ * - `workflowMembers` — anyone named on ANY step of the workflow. The widest
+ *   setting available, and still bounded: it is the workflow's own people, not
+ *   "whoever can see the row". An earlier draft offered `any` for that; it was
+ *   removed because "can see it" is a read permission and archiving is a write,
+ *   so it granted removal to an audience nobody had chosen for the purpose.
+ *
+ * `workflowMembers` here means the same set as {@link SealActors} `workflowMembers`
+ * — the union of every step's members — and is NOT `stepMembers`, which is only
+ * the step a transaction is currently sitting on.
+ */
+export type ArchiveActors = 'initiator' | 'stepMembers' | 'admin' | 'workflowMembers';
+/**
+ * WHO may seal a completed transaction — and, being the same people, who may
+ * reverse a seal while it is still inside its grace window.
+ *
+ * - `authorOrAdmin` — the person who created the transaction, or an
+ *   administrator of its department/organisation. The rule that predates this
+ *   policy, and the default.
+ * - `author` — only the creator.
+ * - `admin` — administrators only. This is the separation-of-duty setting: an
+ *   author who does not administer the department cannot finalise their own
+ *   record. It is expressed through the actor list rather than a separate flag
+ *   because "who may seal" is the only question being asked.
+ * - `initiator` — anyone on the workflow's INITIATE step.
+ * - `workflowMembers` — anyone named on ANY step of the workflow.
+ *
+ * AUTHOR vs INITIATOR are different scopes and must not be conflated. The author
+ * is `FormVal.userId` — whoever created THIS transaction. An initiator is a
+ * member of the workflow's initiate step: a standing permission to START
+ * transactions, held regardless of whether they ever touched this one. The
+ * author is normally also an initiator, but need not be — step membership
+ * changes, and the author of an old record may have left it.
+ *
+ * `workflowMembers` is also NOT the archive policy's `stepMembers`. That one
+ * means the members of the step a transaction is CURRENTLY sitting on; this one
+ * is the union of every step's members. Same-sounding, deliberately different
+ * sets — a sealed transaction has finished, so it sits on no actionable step.
+ */
+export type SealActors = 'authorOrAdmin' | 'author' | 'admin' | 'initiator' | 'workflowMembers';
+/**
+ * Per-workflow rule for sealing its transactions into final records. See
+ * {@link WorkflowModel.sealPolicy}.
+ */
+export interface SealPolicy {
+    /**
+     * Whether this workflow offers sealing at all.
+     *
+     * Sealing is OPT-IN: absent or `false` means the action is not available on
+     * this workflow and the server refuses it. Nothing else in this object is read
+     * while it is off.
+     *
+     * Defaulting to `false` is also what makes the builder's Toggle safe — see the
+     * note on {@link ArchivePolicy.oneWay} for why a true-default boolean cannot be
+     * edited with one.
+     */
+    enabled: boolean;
+    /** Defaults to `'authorOrAdmin'` when absent. */
+    actors?: SealActors;
+    /**
+     * How many days a seal stays reversible.
+     *
+     * Absent means the server's `SEAL_GRACE_DAYS` environment value. `0` makes a
+     * seal permanent the instant it is applied.
+     *
+     * Read ONCE at seal time and stored on the seal as `hardenAt`, an absolute
+     * instant. Changing this never moves the terms a record was already sealed
+     * under — and once `hardenAt` passes, nothing and nobody can reverse that seal
+     * through any interface. That refusal is what the seal is worth.
+     */
+    graceDays?: number;
+}
+/**
+ * Per-workflow rule for archiving its transactions. See
+ * {@link WorkflowModel.archivePolicy}.
+ */
+export interface ArchivePolicy {
+    preset: ArchivePolicyPreset;
+    /**
+     * The `stepId`s at which archiving is offered.
+     *
+     * Required — and only read — when `preset` is `'at-step'`; ignored under every
+     * other preset. Matched against the transaction's `currentStepID`, which is
+     * the same `ProcessStep.stepId` value the engine writes when it advances a
+     * document.
+     *
+     * An id that no longer appears in `processTree` (its step was deleted in the
+     * editor) simply never matches. The engine IGNORES unknown ids rather than
+     * erroring, so deleting a step degrades to "not archivable there" instead of
+     * breaking every transaction on the workflow.
+     */
+    steps?: string[];
+    /** Defaults to `'initiator'` when absent. */
+    actors?: ArchiveActors;
+    /**
+     * Makes archiving final: the engine refuses the restore half of the toggle.
+     *
+     * Defaults to `false` — archive and restore are a single toggle endpoint
+     * (`POST api/form/archiveDocument` flips `archive` whichever way it currently
+     * points), which is the only behaviour that exists today.
+     *
+     * Phrased as "one-way" rather than the more readable `allowRestore` because
+     * the workflow builder edits it with a Toggle, and every Toggle in that panel
+     * binds a boolean whose safe default is `false`. An `allowRestore` field would
+     * default to `true`, so a Toggle emitting `false` for a value the workflow has
+     * never carried would silently make archiving irreversible on every workflow
+     * whose config panel was merely opened.
+     */
+    oneWay?: boolean;
+}
 /**
  * A workflow's STORED fields — everything the application writes, and nothing
  * Mongoose adds for itself (`_id`, `createdAt`, `updatedAt`, `__v`).
@@ -78,8 +225,93 @@ export interface WorkflowModel {
      *
      * Optional, so existing workflow object literals that never set it keep
      * compiling and `StrictSchemaDefinition<IDbWorkflow>` is unaffected.
+     *
+     * See {@link WorkflowModel.uniqueKeysScope} for whether ARCHIVED transactions
+     * still hold their tuple.
      */
     uniqueKeys?: string[];
+    /**
+     * Whether archived transactions still occupy their {@link
+     * WorkflowModel.uniqueKeys} tuple.
+     *
+     * - `'active'` — the duplicate check ignores archived transactions, so
+     *   archiving RELEASES the tuple and a new transaction may re-use it. This is
+     *   the behaviour that predates the field (the engine's duplicate query has
+     *   `archive: false` hard-coded), and so remains the default when absent.
+     * - `'all'` — archived transactions still block. The tuple is claimed for the
+     *   life of the record whatever its storage state; releasing it means
+     *   restoring the transaction and editing the offending value, or deleting it
+     *   outright. Note there is no "archive it out of the way" escape hatch under
+     *   this setting — that is the point of it, but it does mean a mistaken value
+     *   on an archived transaction needs a deliberate correction.
+     *
+     * Only consulted when `uniqueKeys` is non-empty. Enforced by
+     * `FormService.generateFormValues` (osproc-be) at transaction-create time,
+     * which includes or omits `archive: false` in the duplicate query accordingly.
+     *
+     * READ THIS TOGETHER WITH {@link WorkflowModel.archivePolicy}. Archiving is the
+     * only way a transaction leaves the uniqueness pool, so the two fields settle
+     * one question between them: whether archiving is a route around the
+     * constraint. A workflow that both enforces `uniqueKeys` and permits archiving
+     * should set this deliberately rather than inherit the default.
+     */
+    uniqueKeysScope?: 'active' | 'all';
+    /**
+     * When a transaction of this workflow may be archived, and by whom.
+     *
+     * Archiving is a soft delete: `FormVal.archive` flips to `true`, an
+     * `{ isArchived, date, userId }` marker is pushed onto the document's own
+     * `processTree`, and the row moves from the active list to the archived one
+     * (`getArchivedFormValByWorkflowID`). It is reversible unless
+     * {@link ArchivePolicy.oneWay} says otherwise.
+     *
+     * Absent => `{ preset: 'inflight-abandon', actors: 'initiator' }`, which is
+     * exactly what every workflow did before this field existed: the initiator may
+     * abandon a transaction that is still running, and the action is withdrawn
+     * once it reaches a completed end step. Adding the field therefore changes no
+     * existing workflow's behaviour.
+     *
+     * Two guards sit BELOW the policy and are not configurable by it:
+     * - a sealed record can never be archived or restored under any preset
+     *   (`SealedRecordError`) — that is half of what sealing means;
+     * - the server re-checks the whole policy in `FormService.archiveDocument`.
+     *   The client's `canArchive` is a UI affordance only; before this field the
+     *   step and initiator rules lived exclusively in the Angular list projection
+     *   and the endpoint enforced nothing but the seal.
+     *
+     * READ THIS TOGETHER WITH {@link WorkflowModel.uniqueKeysScope} — see the note
+     * there.
+     */
+    archivePolicy?: ArchivePolicy;
+    /**
+     * Whether this workflow's transactions can be sealed into final records, and
+     * on whose terms.
+     *
+     * Sealing makes a completed transaction permanent: it can never again be
+     * edited, checked out, archived, restored or deleted. It is reversible only
+     * inside a grace window recorded on the seal itself as `hardenAt`; past that
+     * instant NO interface and NO role can reverse it, which is the entire value of
+     * the seal.
+     *
+     * OPT-IN. Absent — or `enabled: false` — means this workflow does not offer
+     * sealing at all, and the server refuses the action. This is a deliberate
+     * change from the behaviour that predates the field, where every workflow could
+     * be sealed: finalising a record is a decision about a class of document, not a
+     * capability every workflow should carry by default. Records already sealed
+     * stay sealed, verifiable and reversible-in-window whatever this says — turning
+     * sealing off withdraws the ability to seal ANEW, it does not unseal anything.
+     *
+     * Eligibility is unchanged and NOT configurable: only a transaction that is
+     * complete, unlocked, not a working copy, not archived and not already sealed
+     * can be sealed. {@link SealPolicy.enabled} is a gate in front of those rules,
+     * never a replacement for them.
+     *
+     * READ THIS TOGETHER WITH {@link WorkflowModel.archivePolicy}. Both decide what
+     * may happen to a transaction once it finishes, and they interact: a sealed
+     * transaction can no longer be archived under ANY archive policy, because the
+     * seal guard refuses the write.
+     */
+    sealPolicy?: SealPolicy;
 }
 /**
  * A persisted workflow as it comes back from Mongo: the stored fields plus the

package/dist/interfaces/Workflow/index.d.ts

@@ -1,2 +1,2 @@
-export type { WorkflowModel, DbWorkflowModel } from './WorkflowModel.interface.js';
+export type { WorkflowModel, DbWorkflowModel, ArchivePolicy, ArchivePolicyPreset, ArchiveActors, SealPolicy, SealActors, } from './WorkflowModel.interface.js';
 export type { WorkflowPointingRuleInterface } from './WorkflowPointingRule.interface.js';

package/dist/schemas/Workflow/WorkflowModel.schema.js

@@ -23,6 +23,48 @@ const documentSectionConfigSchema = Joi.object({
         labelConfiguration: Joi.array().required(),
     }).optional(),
 });
+/**
+ * Archive rule for a workflow's transactions — see the `archivePolicy` note on
+ * `WorkflowModel` for what each preset means.
+ *
+ * `steps` is only meaningful under the `at-step` preset, and is required there:
+ * an `at-step` policy with no steps would offer archiving nowhere, which is
+ * `never` written the confusing way. Under every other preset the key is
+ * forbidden rather than merely ignored, so a stale `steps` list cannot sit in a
+ * stored config implying a rule that is not in force.
+ */
+const archivePolicySchema = Joi.object({
+    preset: Joi.string()
+        .valid('inflight-abandon', 'on-completion', 'at-step', 'always', 'never')
+        .required(),
+    steps: Joi.array()
+        .items(Joi.string())
+        .when('preset', {
+        is: 'at-step',
+        then: Joi.array().items(Joi.string()).min(1).required(),
+        otherwise: Joi.forbidden(),
+    }),
+    actors: Joi.string()
+        .valid('initiator', 'stepMembers', 'admin', 'workflowMembers')
+        .optional(),
+    oneWay: Joi.boolean().optional(),
+});
+/**
+ * Sealing rule for a workflow's transactions — see the `sealPolicy` note on
+ * `WorkflowModel`.
+ *
+ * `enabled` is required because the object exists to answer that question;
+ * `actors` and `graceDays` are only meaningful once it is on. `graceDays` is a
+ * whole number of days from zero (0 = permanent immediately) and is capped to
+ * keep a typo from writing a grace window measured in centuries.
+ */
+const sealPolicySchema = Joi.object({
+    enabled: Joi.boolean().required(),
+    actors: Joi.string()
+        .valid('authorOrAdmin', 'author', 'admin', 'initiator', 'workflowMembers')
+        .optional(),
+    graceDays: Joi.number().integer().min(0).max(3650).optional(),
+});
 /**
  * Validates a PERSISTED workflow, i.e. `DbWorkflowModel` — `_id` and the
  * timestamps are required here because this schema is only ever run against a
@@ -53,6 +95,12 @@ export const workflowModelSchema = Joi.object({
     // by the engine at transaction-create time, not by Mongo — see the
     // `uniqueKeys` note on `WorkflowModel`.
     uniqueKeys: Joi.array().items(Joi.string()).optional(),
+    // Whether archiving releases a `uniqueKeys` tuple (`'active'`, the pre-existing
+    // behaviour) or the tuple stays claimed for the life of the record (`'all'`).
+    // Read alongside `archivePolicy` — see both notes on `WorkflowModel`.
+    uniqueKeysScope: Joi.string().valid('active', 'all').optional(),
+    archivePolicy: archivePolicySchema.optional(),
+    sealPolicy: sealPolicySchema.optional(),
 });
 export function validateWorkflowModel(data) {
     const { error } = workflowModelSchema.validate(data, { abortEarly: false });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-t-workflow-typings",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "description": "Typings and interfaces for the ngx-t-workflows library.",
   "keywords": [
     "typings",
@@ -42,14 +42,14 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "peerDependencies": {
-    "ngx-t-forms-types": ">=0.0.16",
+    "ngx-t-forms-types": ">=0.0.27",
     "rxjs": ">=7.8.0"
   },
   "dependencies": {
     "joi": "^18.0.2"
   },
   "devDependencies": {
-    "ngx-t-forms-types": "^0.0.16",
+    "ngx-t-forms-types": "^0.0.27",
     "rimraf": "^6.1.3",
     "typescript": "^5.9.3"
   }