ngx-t-workflow-typings 3.0.1 → 3.1.0

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;

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 { 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/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,
@@ -806,6 +791,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.",
         ],
     },
     /* ====================================================================== */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-t-workflow-typings",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Typings and interfaces for the ngx-t-workflows library.",
   "keywords": [
     "typings",