[dev] [Marfuen] mariano/nist-sp800-53-readiness

apps/api/src/framework-editor-versions/framework-manifest-builder.ts

@@ -60,6 +60,7 @@ export async function buildManifestForFramework(frameworkId: string): Promise<Fr
           id: ct.id,
           name: ct.name,
           description: ct.description,
+          controlFamily: ct.controlFamily || null,
           requirementIds: ct.requirements
             .map((r) => r.id)
             .filter((id) => ownRequirementIds.has(id)),

apps/api/src/framework-editor/control-template/control-template.service.ts

@@ -105,6 +105,7 @@ export class ControlTemplateService {
         data: {
           name: dto.name,
           description: dto.description ?? '',
+          controlFamily: dto.controlFamily || null,
         },
       });
       this.logger.log(`Created control template: ${ct.name} (${ct.id})`);
@@ -120,6 +121,7 @@ export class ControlTemplateService {
         data: {
           name: dto.name,
           description: dto.description ?? '',
+          controlFamily: dto.controlFamily || null,
         },
       });
       await tx.frameworkEditorControlDocumentTypeLink.createMany({
@@ -144,6 +146,7 @@ export class ControlTemplateService {
         data: {
           ...(dto.name !== undefined && { name: dto.name }),
           ...(dto.description !== undefined && { description: dto.description }),
+          ...(dto.controlFamily !== undefined && { controlFamily: dto.controlFamily || null }),
         },
       });
       this.logger.log(`Updated control template: ${updated.name} (${id})`);
@@ -163,6 +166,7 @@ export class ControlTemplateService {
         data: {
           ...(dto.name !== undefined && { name: dto.name }),
           ...(dto.description !== undefined && { description: dto.description }),
+          ...(dto.controlFamily !== undefined && { controlFamily: dto.controlFamily || null }),
         },
       });
       await tx.frameworkEditorControlDocumentTypeLink.deleteMany({

apps/api/src/framework-editor/control-template/dto/create-control-template.dto.ts

@@ -19,6 +19,12 @@ export class CreateControlTemplateDto {
   @MaxLength(5000)
   description: string;
 
+  @ApiPropertyOptional({ example: 'AC - Access Control' })
+  @IsString()
+  @IsOptional()
+  @MaxLength(255)
+  controlFamily?: string;
+
   @ApiPropertyOptional({ example: ['penetration-test', 'rbac-matrix'] })
   @IsArray()
   @IsString({ each: true })

apps/api/src/framework-editor/framework/dto/import-framework.dto.ts

@@ -80,6 +80,12 @@ class ImportControlTemplateDto {
   @MaxLength(5000)
   description: string;
 
+  @ApiPropertyOptional({ example: 'AC - Access Control' })
+  @IsString()
+  @IsOptional()
+  @MaxLength(255)
+  controlFamily?: string;
+
   @ApiPropertyOptional()
   @IsArray()
   @ArrayMaxSize(50)

apps/api/src/framework-editor/framework/framework-export.service.ts

@@ -24,6 +24,7 @@ export interface ExportedFramework {
   controlTemplates: Array<{
     name: string;
     description: string;
+    controlFamily: string | null;
     documentTypes: string[];
     requirementIndices: number[];
     policyTemplateIndices: number[];
@@ -131,6 +132,7 @@ export class FrameworkExportService {
       controlTemplates: controlTemplates.map((ct) => ({
         name: ct.name,
         description: ct.description,
+        controlFamily: ct.controlFamily ?? null,
         documentTypes: ct.frameworkDocumentLinks.map((link) => link.formType),
         requirementIndices: ct.requirements
           .map((r) => reqIdToIndex.get(r.id))
@@ -225,6 +227,7 @@ export class FrameworkExportService {
             data: {
               name: ct.name,
               description: ct.description,
+              controlFamily: ct.controlFamily ?? null,
               requirements: {
                 connect: (ct.requirementIndices ?? []).map((i) => ({
                   id: createdRequirements[i].id,

apps/api/src/frameworks/framework-versioning/framework-diff.ts

@@ -169,7 +169,7 @@ function edgesFromControls<E>(
 }
 
 function controlEqual(a: ManifestControl, b: ManifestControl): boolean {
-  return a.name === b.name && a.description === b.description;
+  return a.name === b.name && a.description === b.description && (a.controlFamily ?? null) === (b.controlFamily ?? null);
 }
 
 function requirementEqual(a: ManifestRequirement, b: ManifestRequirement): boolean {

apps/api/src/frameworks/framework-versioning/framework-rollback.service.ts

@@ -311,6 +311,30 @@ async function replayUndo(
     });
   }
 
+  // Restore control families — guarded so older undo payloads without
+  // this bucket don't break rollback.
+  if (ctx.undo.controlFamilies) {
+    for (const entry of ctx.undo.controlFamilies.created) {
+      await tx.frameworkControlFamily.deleteMany({
+        where: { frameworkInstanceId: entry.frameworkInstanceId, controlId: entry.controlId },
+      });
+    }
+    for (const entry of ctx.undo.controlFamilies.updated) {
+      await tx.frameworkControlFamily.upsert({
+        where: { frameworkInstanceId_controlId: { frameworkInstanceId: entry.frameworkInstanceId, controlId: entry.controlId } },
+        create: { frameworkInstanceId: entry.frameworkInstanceId, controlId: entry.controlId, controlFamily: entry.prevFamily },
+        update: { controlFamily: entry.prevFamily },
+      });
+    }
+    for (const entry of ctx.undo.controlFamilies.deleted) {
+      await tx.frameworkControlFamily.upsert({
+        where: { frameworkInstanceId_controlId: { frameworkInstanceId: entry.frameworkInstanceId, controlId: entry.controlId } },
+        create: { frameworkInstanceId: entry.frameworkInstanceId, controlId: entry.controlId, controlFamily: entry.prevFamily },
+        update: { controlFamily: entry.prevFamily },
+      });
+    }
+  }
+
   // Revert framework instance version pointer
   await tx.frameworkInstance.update({
     where: { id: ctx.syncOp.frameworkInstanceId },

apps/api/src/frameworks/framework-versioning/framework-sync-apply.ts

@@ -60,6 +60,7 @@ export async function applySync(
     frameworkControlPolicyLinks: { connected: [], disconnected: [] },
     frameworkControlTaskLinks: { connected: [], disconnected: [] },
     frameworkControlDocumentTypeLinks: { connected: [], disconnected: [] },
+    controlFamilies: { created: [], updated: [], deleted: [] },
   };
   const summary: SyncSummary = {
     controlsAdded: 0, controlsArchived: 0, controlsUpdatedApplied: 0, controlsUpdatedPreserved: 0,
@@ -83,6 +84,20 @@ export async function applySync(
     ctlByTemplate.set(targetControl.id, created);
     undo.controls.created.push(created.id);
     summary.controlsAdded += 1;
+    // Per-instance family entry for the new control
+    if (targetControl.controlFamily) {
+      await tx.frameworkControlFamily.create({
+        data: {
+          frameworkInstanceId: ctx.instance.id,
+          controlId: created.id,
+          controlFamily: targetControl.controlFamily,
+        },
+      });
+      undo.controlFamilies!.created.push({
+        frameworkInstanceId: ctx.instance.id,
+        controlId: created.id,
+      });
+    }
   }
   for (const removed of diff.controls.removed) {
     const inst = ctlByTemplate.get(removed.id);
@@ -96,6 +111,42 @@ export async function applySync(
   for (const u of diff.controls.updated) {
     const inst = ctlByTemplate.get(u.id);
     if (!inst) continue;
+
+    // Sync family assignment regardless of whether the control content was edited.
+    // Family is structural metadata, not user-authored content.
+    const existingFamily = await tx.frameworkControlFamily.findUnique({
+      where: { frameworkInstanceId_controlId: { frameworkInstanceId: ctx.instance.id, controlId: inst.id } },
+      select: { controlFamily: true },
+    });
+    if (u.to.controlFamily) {
+      await tx.frameworkControlFamily.upsert({
+        where: { frameworkInstanceId_controlId: { frameworkInstanceId: ctx.instance.id, controlId: inst.id } },
+        create: { frameworkInstanceId: ctx.instance.id, controlId: inst.id, controlFamily: u.to.controlFamily },
+        update: { controlFamily: u.to.controlFamily },
+      });
+      if (existingFamily) {
+        undo.controlFamilies!.updated.push({
+          frameworkInstanceId: ctx.instance.id,
+          controlId: inst.id,
+          prevFamily: existingFamily.controlFamily,
+        });
+      } else {
+        undo.controlFamilies!.created.push({
+          frameworkInstanceId: ctx.instance.id,
+          controlId: inst.id,
+        });
+      }
+    } else if (existingFamily) {
+      await tx.frameworkControlFamily.deleteMany({
+        where: { frameworkInstanceId: ctx.instance.id, controlId: inst.id },
+      });
+      undo.controlFamilies!.deleted.push({
+        frameworkInstanceId: ctx.instance.id,
+        controlId: inst.id,
+        prevFamily: existingFamily.controlFamily,
+      });
+    }
+
     if (isControlEdited(inst, u.from)) {
       summary.controlsUpdatedPreserved += 1;
       continue;

apps/api/src/frameworks/framework-versioning/manifest.types.ts

@@ -26,6 +26,7 @@ export interface ManifestControl {
   id: string; // frk_ct_*
   name: string;
   description: string;
+  controlFamily?: string | null;
   requirementIds: string[];
   policyIds: string[];
   taskIds: string[];

apps/api/src/frameworks/framework-versioning/undo-payload.types.ts

@@ -15,6 +15,8 @@ export interface UndoPayload {
   frameworkControlPolicyLinks?: ImplicitEdgeBucket;
   frameworkControlTaskLinks?: ImplicitEdgeBucket;
   frameworkControlDocumentTypeLinks?: ImplicitEdgeBucket;
+  // Per-instance control family assignments. Older syncs may not have this bucket.
+  controlFamilies?: ControlFamilyUndoBucket;
 }
 
 export interface EntityUndoBucket<Content> {
@@ -75,6 +77,17 @@ export interface ImplicitEdgeBucket {
   disconnected: Array<{ controlId: string; otherId: string }>;
 }
 
+/**
+ * Tracks FrameworkControlFamily changes so rollback can restore prior state.
+ * `created` entries are deleted on rollback; `updated` entries are restored to
+ * prevFamily; `deleted` entries are recreated with prevFamily.
+ */
+export interface ControlFamilyUndoBucket {
+  created: Array<{ frameworkInstanceId: string; controlId: string }>;
+  updated: Array<{ frameworkInstanceId: string; controlId: string; prevFamily: string }>;
+  deleted: Array<{ frameworkInstanceId: string; controlId: string; prevFamily: string }>;
+}
+
 export interface SyncSummary {
   controlsAdded: number;
   controlsArchived: number;

apps/api/src/frameworks/frameworks-source-loader.helper.ts

@@ -19,6 +19,7 @@ export interface LoadedFrameworkSources {
     id: string;
     name: string;
     description: string;
+    controlFamily?: string | null;
     documentTypes: EvidenceFormType[];
   }>;
   policyTemplates: Array<{
@@ -133,6 +134,7 @@ export async function loadFrameworkSources({
           id: c.id,
           name: c.name,
           description: c.description,
+          controlFamily: c.controlFamily,
           documentTypes: (c.documentTypes ?? []) as EvidenceFormType[],
         });
       }
@@ -211,14 +213,15 @@ export async function loadFrameworkSources({
 
     const liveControls = await tx.frameworkEditorControlTemplate.findMany({
       where: { requirements: { some: { id: { in: fallbackRequirementIds } } } },
-      select: { id: true, name: true, description: true, documentTypes: true },
+      select: { id: true, name: true, description: true, controlFamily: true, documentTypes: true },
     });
     for (const lc of liveControls) {
       if (!controlsMap.has(lc.id)) {
         controlsMap.set(lc.id, {
           id: lc.id,
           name: lc.name,
           description: lc.description,
+          controlFamily: lc.controlFamily ?? undefined,
           documentTypes: lc.documentTypes,
         });
       }

apps/api/src/frameworks/frameworks-upsert.helper.ts

@@ -285,6 +285,7 @@ export async function upsertOrgFrameworkStructure({
   const frameworkControlPolicyEntries: Prisma.FrameworkControlPolicyLinkCreateManyInput[] = [];
   const frameworkControlTaskEntries: Prisma.FrameworkControlTaskLinkCreateManyInput[] = [];
   const frameworkControlDocumentTypeEntries: Prisma.FrameworkControlDocumentTypeLinkCreateManyInput[] = [];
+  const frameworkControlFamilyEntries: Prisma.FrameworkControlFamilyCreateManyInput[] = [];
   const controlTemplateById = new Map(controlTemplates.map((c) => [c.id, c]));
 
   for (const relation of groupedRelations) {
@@ -360,6 +361,16 @@ export async function upsertOrgFrameworkStructure({
         formType,
       });
     }
+
+    // FrameworkControlFamily: per-instance family grouping from the template.
+    const template = controlTemplateById.get(relation.controlTemplateId);
+    if (template?.controlFamily) {
+      frameworkControlFamilyEntries.push({
+        frameworkInstanceId,
+        controlId,
+        controlFamily: template.controlFamily,
+      });
+    }
   }
 
   if (requirementMapEntries.length > 0) {
@@ -397,6 +408,13 @@ export async function upsertOrgFrameworkStructure({
     });
   }
 
+  if (frameworkControlFamilyEntries.length > 0) {
+    await tx.frameworkControlFamily.createMany({
+      data: frameworkControlFamilyEntries,
+      skipDuplicates: true,
+    });
+  }
+
   return {
     processedFrameworks: frameworkEditorFrameworks,
     controlTemplates,

apps/api/src/frameworks/frameworks.service.ts

@@ -165,6 +165,9 @@ export class FrameworksService {
                     },
                   },
                   frameworkDocumentLinks: true,
+                  frameworkControlFamilies: {
+                    select: { frameworkInstanceId: true, controlFamily: true },
+                  },
                   requirementsMapped: { where: { archivedAt: null } },
                 },
               },
@@ -189,6 +192,7 @@ export class FrameworksService {
             requirementsMapped: _,
             frameworkPolicyLinks,
             frameworkDocumentLinks,
+            frameworkControlFamilies,
             ...controlData
           } = rm.control;
           const policyLinks = rm.control.frameworkPolicyLinks.filter(
@@ -199,8 +203,13 @@ export class FrameworksService {
             (link: { frameworkInstanceId: string }) =>
               link.frameworkInstanceId === fi.id,
           );
+          const familyEntry = (frameworkControlFamilies ?? []).find(
+            (f: { frameworkInstanceId: string }) =>
+              f.frameworkInstanceId === fi.id,
+          );
           controlsMap.set(rm.control.id, {
             ...controlData,
+            controlFamily: familyEntry?.controlFamily ?? null,
             policies: policyLinks.map(
               (link: { policy: { id: string; name: string; status: string } }) =>
                 link.policy,
@@ -286,6 +295,11 @@ export class FrameworksService {
                 frameworkDocumentLinks: {
                   where: { frameworkInstanceId },
                 },
+                frameworkControlFamilies: {
+                  where: { frameworkInstanceId },
+                  select: { controlFamily: true },
+                  take: 1,
+                },
               },
             },
           },
@@ -307,10 +321,12 @@ export class FrameworksService {
           requirementsMapped: _,
           frameworkPolicyLinks,
           frameworkDocumentLinks,
+          frameworkControlFamilies,
           ...controlData
         } = rm.control;
         controlsMap.set(rm.control.id, {
           ...controlData,
+          controlFamily: frameworkControlFamilies?.[0]?.controlFamily ?? null,
           policies:
             rm.control.frameworkPolicyLinks?.map((link) => link.policy) || [],
           requirementsMapped: rm.control.requirementsMapped || [],
@@ -797,6 +813,11 @@ export class FrameworksService {
               frameworkDocumentLinks: {
                 where: { frameworkInstanceId },
               },
+              frameworkControlFamilies: {
+                where: { frameworkInstanceId },
+                select: { controlFamily: true },
+                take: 1,
+              },
             },
           },
         },
@@ -849,10 +870,12 @@ export class FrameworksService {
           const {
             frameworkPolicyLinks,
             frameworkDocumentLinks,
+            frameworkControlFamilies,
             ...control
           } = relatedControl.control;
           return {
             ...control,
+            controlFamily: frameworkControlFamilies?.[0]?.controlFamily ?? null,
             policies: frameworkPolicyLinks.map((link) => link.policy),
             controlDocumentTypes: frameworkDocumentLinks.map(
               (documentType) => ({